Documentation
¶
Overview ¶
Package atomicfile provides crash-safe atomic file writes via the temp → fsync → rename → dir-fsync sequence, with path validation and bounded reads. Standard-library only.
Result and durability ¶
The write primitives (WriteFile, WriteReader, WriteFileInRoot, WriteReaderInRoot, and PendingFile.Commit) return a Result alongside an error. A nil error means the data reached its final path; the write either fully succeeded or, at worst, was renamed into place but a directory fsync failed. Result.Durable distinguishes those two outcomes: it is true only when the file and every directory its path depends on were fsynced — the file, its parent, and each parent the write created under WithMkdirMode — so a caller that cares about crash durability inspects Result.Durable rather than decoding error types. A non-nil error always means the data did NOT reach its final path.
Temp files ¶
Every temp file this package creates is named ".atomicfile-<digits>.tmp" (the digits are a crypto/rand decimal string). CleanupStaleTemps reclaims orphaned temps of exactly that shape and nothing else, so it never deletes a caller-owned file.
That shape is part of the API, not an implementation detail, because a caller staging its own file in a swept directory has to agree with it: TempName produces a name the sweeps reclaim and IsPackageTemp reports whether a name is one, so the agreement is a contract a test can pin rather than a convention rebuilt from os.CreateTemp's undocumented substitution.
Orphans, and who reclaims them ¶
A temp exists on disk between its creation and the rename that publishes it. Each write removes its own temp on every failure path, but a deferred removal only runs if the process lives to run it: SIGKILL does not, and neither does Go's default SIGINT/SIGTERM handling, which exits without unwinding. A power loss, an OOM kill, or a `docker stop` that escalates therefore leaves a temp behind, and so does a PendingFile a caller abandons without Commit or Cleanup. The atomicity guarantee is unaffected — nothing was published, and the previous file at the target is untouched — so an orphan costs disk, not correctness.
Nothing in this package reclaims them on its own. There is no background sweeper, no finalizer, and no cleanup on the next write: reclamation is CleanupStaleTemps (or CleanupStaleTempsInRoot), called by the consumer where it knows a sweep is safe — at startup, or on a schedule. A finalizer was considered and rejected: an unlink with no ordering guarantee against a live Commit would make abandonment silently work sometimes, which is worse than deterministically leaving a file a shape-matched sweep can identify.
A publish-by-linkat over O_TMPFILE would leave no name to orphan at all, and does not fit: linkat cannot replace an existing entry, so publishing over a previous generation still needs a named temp and a rename.
The one interaction to get right is maxAge, which both sweeps document: it has to exceed the longest time any concurrent writer may hold a temp, or the sweep unlinks a live one.
Path validation ¶
ValidatePath is the acceptance check the absolute-path entry points apply, exported for callers that have to accept or refuse a path long before they write to it — a config value read at startup, a CLI flag, a request field. filepath.IsAbs is the usual stand-in and admits a path with an embedded NUL that every write here refuses, so validating with it accepts input the write path rejects later. The exported gate delegates to the same private validator the writes use, so the two verdicts cannot drift; it touches nothing on disk, which also means a nil answer says the path is well formed, not that a write will succeed (that is ProbeWritable's question).
Writability probes ¶
ProbeWritable and ProbeWritableInRoot answer "can this process actually write here?" — the preflight question a stat of the mode bits gets wrong on an NFS or FUSE mount, a read-only bind mount, or a Docker volume owned by another UID. They walk the full ladder a real write walks (mkdir, create, write, sync, close, remove) and report which stage failed in a ProbeResult rather than as an error, so a caller that warns on a failed cleanup and one that treats it as fatal both get what they need. The probe file carries the package temp shape, so a probe leaked by a crash is swept like any other orphan.
Size bounds ¶
ReadBounded and ReadBoundedFile refuse to read a file past a byte limit, and WithMaxBytes mirrors that bound on the write side across every write primitive: a writer that also owns the reader can refuse to persist a file its own read path would refuse to load, instead of failing open on the next read. The cap is enforced twice: on the staged stream as bytes arrive, and against the staged file's actual size at the durability barrier before publication, so content staged outside the streaming interfaces cannot publish either. Both directions report ErrFileTooLarge, and a capped write always leaves the previous file at the target path intact.
Safe opens ¶
OpenRegularInRoot and OpenRegular hand back the OPEN DESCRIPTOR of a file already known to be a regular one, which is the reusable half of the read sequence: open (confined to a root, or refusing a final-component symlink outright), stat the handle rather than the pathname, refuse a directory, FIFO, device node or socket. ReadBoundedInRoot is now literally OpenRegularInRoot plus ReadBoundedFile, so the sequence has one home.
A caller that STREAMS the file through a decoder or decryptor never materializes its bytes, and a caller caching the file needs the FileInfo the bytes came from in order to record a FileIdentity; neither can use a []byte-returning helper. Both are the same argument: binding the shape check, the identity and the read to ONE descriptor is what closes the window a second pathname observation opens, where a rename in between lets a caller decode one generation's bytes while recording another's identity and turns every non-regular-file rejection back into a check-then-open race.
The two refusals differ because the mechanisms do. The root-confined form bounds where the open can land but still traverses a symlink inside the tree (that is what an *os.Root promises); the ambient form opens O_NOFOLLOW, so the kernel itself refuses a symlink under the name and reports ErrSymlinkTarget, the same vocabulary the write side uses. Neither pins the ancestor components — OpenParentInRoot does that.
Private directories and enforced modes ¶
A mode passed to mkdir(2) or open(2) is a REQUEST. umask narrows it, and a filesystem carrying an inheritable ACL can widen the result regardless of what was asked — measured on a ZFS nfs4acl dataset, an inheritable group@:rwx ACE stores 0770 for a 0o700 mkdir, and tightening the parent does not cover it. chmod(2) is the only call that SETS a mode, and a caller that stops there has issued a second request rather than confirmed a result.
EnforceMode closes that loop on an OPEN HANDLE: fchmod then fstat the same descriptor, returning the mode the filesystem actually stored and refusing a mismatch with ErrModeNotStored. It takes an *os.File, so a file and a directory are the same call, and it observes no pathname — a chmod-then-stat by name can chmod one object and certify another.
The write path uses it on itself, in three places. The staging file is created owner-only and PROVED owner-only before the caller's payload goes into it — the temp has to share the target's parent directory, so on a widening filesystem it would otherwise hold the payload group-readable and group-writable for the whole write. Then WithMode's mode is enforced rather than merely requested before the rename publishes it, so a filesystem that refuses the mode fails the write instead of publishing a wider file. And each directory WithMkdirMode creates is enforced as it is made, since a mode narrowed by umask or widened by an ACL on the directory holding the file is the same defect one level up.
EnsurePrivateDir is the custody composition around it, for a process establishing a directory only its own user may enter inside a parent others can write: mkdir 0700 recording whether THIS call created it, open O_DIRECTORY|O_NOFOLLOW so a planted symlink is refused rather than followed and a planted FIFO cannot stall the open, fstat the handle, require the effective uid to own it, then EnforceMode a directory it created (the ACL repair, safe because nobody else ever held that name) while REFUSING a pre-existing one that grants group or other access (repairing another principal's directory would take over their name). One level per call: a multi-level path is the caller's loop, because only the caller knows which levels are its own.
The verdict is POINT-IN-TIME. It proves what was true of one inode while a handle was open on it; it does not pin the directory for later use, and a caller that goes on to ReadDir or Remove through the PATHNAME re-opens the window the check closed. Acting through a retained handle (an *os.Root) is what would close that, and is a different API shape.
Reload staleness ¶
FileIdentity answers "is what I loaded still what is on disk?" from a stat alone, for a reader caching a file another process publishes. The correct form of that test is knowledge about this package's write barrier. Matches compares mtime equality AND os.SameFile identity, because an in-place writer keeps the inode while usually moving the mtime, and a publish-by-rename installs a different inode that a restore can hand the OLD timestamp. Either leg alone serves stale content for one of the two write mechanisms. Usually, because inode times come from a coarse clock tick: two writes inside one tick carry byte-identical mtimes, so an in-place rewrite there moves neither leg and a changed LENGTH is the only thing left that can see it. Size is therefore a third leg rather than a redundant one, and a caller whose file may be rewritten in place keeps a size comparison beside Changed. It is a comparison primitive, not a policy — degradation states, stat-error handling, and re-stat cadence stay with the caller.
Confinement ¶
Every write runs through an *os.Root: the *InRoot functions use the caller's root directly, and the absolute-path functions open the target's parent directory as a root and write through it. The absolute-path surface is therefore a thin adapter over one confined write engine. WithMkdirMode's directory creation runs through a root too — one opened on the deepest ancestor that already exists, so every level the write ADDS is created openat-relative rather than by ambient path resolution.
Confined traversal and removal ¶
An *os.Root confines a path but does not PIN it: a root deliberately follows a symlink component that stays inside its tree, so a multi-component name that is stat-ed and then operated on can address two different files if an ancestor directory is swapped for a symlink in between. Confinement still holds — nothing outside the root is reachable — and inside the tree the operation lands somewhere the caller never inspected.
OpenParentInRoot closes that window: it descends component by component, refusing a symlink and confirming each directory's identity with os.SameFile, and hands back the leaf's own pinned root plus its base name, so the operation that follows names no ancestor at all. RemoveFileInRoot is that descent applied to an unlink, and CleanupStaleTempsInRoot now reclaims every temp through it.
WalkDirInRoot is the traversal counterpart to WriteFileInRoot and ReadBoundedInRoot, for a caller enumerating a tree it does not own: entries stream in fixed ReadDir batches rather than one materialized (and sorted) inventory per directory, exactly one directory handle is open at a time, each directory is opened O_DIRECTORY so a planted FIFO is refused instead of blocking the caller's goroutine, and a symlinked directory is never descended. The callback is an fs.WalkDirFunc and the fs.SkipDir/fs.SkipAll sentinels behave as they do in fs.WalkDir; the two deliberate differences are that entries arrive in directory order (sorted within a batch only) and that a directory's own entries are all visited before the walk descends.
Index ¶
- Variables
- func EnforceMode(f *os.File, want os.FileMode) (os.FileMode, error)
- func IsPackageTemp(name string) bool
- func OpenParentInRoot(root *os.Root, name string) (*os.Root, string, error)
- func OpenRegular(path string) (*os.File, os.FileInfo, error)
- func OpenRegularInRoot(root *os.Root, name string) (*os.File, os.FileInfo, error)
- func OpenRegularInRootNoFollow(root *os.Root, name string) (*os.File, os.FileInfo, error)
- func ReadBounded(ctx context.Context, path string, maxBytes int64) ([]byte, error)
- func ReadBoundedFile(ctx context.Context, f *os.File, maxBytes int64) ([]byte, error)
- func ReadBoundedInRoot(ctx context.Context, root *os.Root, name string, maxBytes int64) ([]byte, error)
- func RemoveFileInRoot(root *os.Root, name string) error
- func TempName() string
- func ValidatePath(path string) error
- func WalkDirInRoot(ctx context.Context, root *os.Root, fn fs.WalkDirFunc) error
- type FileIdentity
- type NotRegularError
- type Option
- type PendingFile
- func (p *PendingFile) BytesWritten() int64
- func (p *PendingFile) Cleanup() error
- func (p *PendingFile) Commit(ctx context.Context) (Result, error)
- func (p *PendingFile) ReadFrom(r io.Reader) (int64, error)
- func (p *PendingFile) Truncate(size int64) error
- func (p *PendingFile) Write(b []byte) (int, error)
- func (p *PendingFile) WriteString(s string) (int, error)
- type PrivateDir
- type ProbeResult
- type ProbeStage
- type Result
- func WriteFile(ctx context.Context, path string, data []byte, opts ...Option) (Result, error)
- func WriteFileInRoot(ctx context.Context, root *os.Root, name string, data []byte, opts ...Option) (Result, error)
- func WriteReader(ctx context.Context, path string, r io.Reader, opts ...Option) (Result, error)
- func WriteReaderInRoot(ctx context.Context, root *os.Root, name string, r io.Reader, opts ...Option) (Result, error)
- type SweepResult
- type WriteError
- type WritePhase
Examples ¶
- CleanupStaleTemps
- CleanupStaleTempsInRoot
- EnforceMode
- EnsurePrivateDir
- EnsurePrivateDir (Refusals)
- NewPendingFile
- NewPendingFileInRoot
- OpenRegular
- OpenRegularInRoot
- PendingFile
- ProbeWritable
- ProbeWritableInRoot
- ReadBounded
- ReadBoundedInRoot
- RemoveFileInRoot
- TempName
- WalkDirInRoot
- WriteFile
- WriteFile (WithMkdirMode)
- WriteFile (WithMode)
- WriteFileInRoot
- WriteReader
- WriteReader (WithMode)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEmptyPath is returned when a path argument is empty. ErrEmptyPath = errors.New("atomicfile: empty path") // ErrUnsafePath is returned when a path fails the local safety check. ErrUnsafePath = errors.New("atomicfile: unsafe path") // ErrFileTooLarge is returned when a file exceeds the ReadBounded / // ReadBoundedFile size limit, or content exceeds a WithMaxBytes write cap // (there it may arrive wrapped, sometimes inside a *WriteError; match with // errors.Is). ErrFileTooLarge = errors.New("atomicfile: file too large") // ErrSymlinkTarget is returned when the target path is a symlink, which // every write entry point, OpenRegular and OpenRegularInRootNoFollow refuse. ErrSymlinkTarget = errors.New("atomicfile: target is a symlink") // ErrRaced is returned by OpenRegularInRootNoFollow when the name changed // identity between the check that refused a symlink and the open that // followed it, so the refusal could not be shown to cover the descriptor // handed back. A retry is the sane response, unlike ErrSymlinkTarget, which // is a permanent verdict about what is at the name. Match with errors.Is. ErrRaced = errors.New("atomicfile: path changed between the check and the open") // ErrNotRegular is returned when a name resolves to something other than a // regular file. ReadBoundedInRoot refuses to read it, RemoveFileInRoot // refuses to unlink it, and every write entry point refuses to publish over // it. Match with errors.Is; for the mode itself, errors.As a // *NotRegularError rather than parsing the message. ErrNotRegular = errors.New("atomicfile: not a regular file") // ErrNotDirectory is returned by EnsurePrivateDir when the name is occupied // by something other than a directory. Match with errors.Is. ErrNotDirectory = errors.New("atomicfile: not a directory") // ErrNotOwned is returned by EnsurePrivateDir when the directory's owner is // not the effective uid, or ownership could not be determined. Match with // errors.Is. ErrNotOwned = errors.New("atomicfile: directory not owned by the effective uid") // ErrModeTooOpen is returned by EnsurePrivateDir when a pre-existing // directory grants group or other access; it is deliberately not repaired // unless WithRepairOwnedDir is set. Match with errors.Is. ErrModeTooOpen = errors.New("atomicfile: directory mode grants group or other access") // ErrModeNotStored is returned by EnforceMode when the mode read back from // the handle after chmod does not match what was requested — a mount // property, not a permission error. Match with errors.Is. ErrModeNotStored = errors.New("atomicfile: filesystem did not store the requested mode") // ErrAborted is returned by PendingFile.Commit when the pending file was // already aborted by a prior Cleanup. ErrAborted = errors.New("atomicfile: pending file aborted") )
Functions ¶
func EnforceMode ¶
EnforceMode sets want on the OPEN HANDLE f and returns the mode the filesystem actually stored, having already refused a mismatch.
A mode argument is a REQUEST, not a result: mkdir(2)/open(2) apply umask, and an inheritable ACL can widen the outcome regardless of what was asked (measured on ZFS nfs4acl: 0o700 mkdir stores 0770). chmod(2) only SETS a mode, so the sequence here is chmod then stat — the stat is what turns "asked for 0600" into "is 0600".
Both calls run on the open descriptor (fchmod/fstat), not the pathname, so a rename between two path-based observations cannot certify the wrong file. Works for a file or a directory, both being an *os.File.
Only the bits chmod(2) can set are compared (permission bits plus setuid/setgid/sticky), so a directory's type bits never read as a mismatch, and setgid is included on purpose: Linux inherits it from a setgid parent.
A mismatch returns ErrModeNotStored naming both modes, with the stored mode returned alongside so a caller that warns and continues need not re-stat. Every other error is the filesystem's own, unwrapped.
Example ¶
package main
import (
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, "secret.json")
_ = os.WriteFile(path, []byte(`{}`), 0o644)
f, _ := os.Open(path)
defer f.Close()
// The mode a create or a chmod takes is a REQUEST; the returned mode is what
// the filesystem stored, read back from the same descriptor that was chmod'ed.
stored, err := atomicfile.EnforceMode(f, 0o600)
fmt.Printf("stored %#o, err %v\n", stored, err)
}
Output: stored 0600, err <nil>
func IsPackageTemp ¶
IsPackageTemp reports whether name is a temp file this package created: ".atomicfile-<digits>.tmp", with a non-empty all-digit middle.
A file merely sharing the prefix and suffix (".atomicfile-notes.tmp") is NOT a package temp and no sweep will ever delete it. name is a single directory-entry name, not a path; pass filepath.Base(path) if you hold a path.
func OpenParentInRoot ¶
OpenParentInRoot opens the parent directory of name as its own *os.Root, pinned to the directory that was inspected, and returns that root together with name's final element.
*os.Root confines a path but does not pin it: it FOLLOWS an in-root symlink component, so a multi-component name that is stat-ed and then operated on can address two different files if an ancestor directory is swapped for a symlink in between. The descent here closes that window: each component is Lstat-ed (a symlink is refused, not followed), required to be a real directory, opened as its own root, and confirmed with os.SameFile against what was inspected. Naming only the returned base through the returned root then removes every ancestor from the operation's path.
Reach for it whenever two operations on one path must address the same file and the tree is one other writers can modify. A single operation through the caller's own root needs none of this.
The returned root is ALWAYS a fresh handle the caller must close, even for a name directly under root, so the close never risks closing the caller's root. The caller owns root; OpenParentInRoot does not close it.
A vanished component matches fs.ErrNotExist, a denied one matches fs.ErrPermission, and a component that is not a real directory — or changed identity mid-open — is refused naming the component. name must be relative and name an entry: "." and ".." are refused with ErrUnsafePath.
func OpenRegular ¶
OpenRegular opens the absolute path read-only and returns the open descriptor together with the FileInfo of that same descriptor, refusing a symlink at the final component and anything that is not a regular file. The caller owns the returned file and closes it.
It is the ambient-path sibling of OpenRegularInRoot, for a caller holding a full path into a directory it trusts rather than an *os.Root. The refusals differ because the mechanisms do: O_NOFOLLOW makes the KERNEL refuse a final-component symlink (reported as ErrSymlinkTarget), where the root-confined form lets an in-root symlink resolve and only bounds where it can land. Neither pins the ANCESTOR components.
This does not change ReadBounded, which follows symlinks by design; a caller wanting the refusal asks for it here.
Errors: ErrEmptyPath or ErrUnsafePath for an empty, NUL-holding, or non-absolute path; ErrSymlinkTarget when the kernel refuses the open because the final component is a symlink; ErrNotRegular for a directory, FIFO, device node or socket, naming the actual mode; the filesystem's own error otherwise (a missing file matches fs.ErrNotExist). ELOOP from a symlink loop in an ANCESTOR component takes the same ErrSymlinkTarget arm as the final-component refusal; a caller that must tell them apart reads the wrapped error.
Example ¶
package main
import (
"errors"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
target := filepath.Join(dir, "state.json")
_ = os.WriteFile(target, []byte(`{}`), 0o600)
link := filepath.Join(dir, "state-link.json")
_ = os.Symlink(target, link)
f, _, err := atomicfile.OpenRegular(target)
if err == nil {
f.Close()
}
fmt.Println("regular file:", err)
// O_NOFOLLOW has the kernel refuse a symlink under the name, so there is no
// check-then-open window. ReadBounded still follows links by design.
_, _, err = atomicfile.OpenRegular(link)
fmt.Println("symlink:", errors.Is(err, atomicfile.ErrSymlinkTarget))
}
Output: regular file: <nil> symlink: true
func OpenRegularInRoot ¶
OpenRegularInRoot opens name inside root read-only and returns the open descriptor together with the FileInfo of that same descriptor, having already refused anything that is not a regular file. The caller owns the returned file and closes it; root stays the caller's too.
It is the open half of ReadBoundedInRoot, which is built on it: open through the root (so a symlink or ".." in name cannot escape its tree), non-blocking so a planted FIFO cannot stall the caller in open(2), then stat the OPEN HANDLE — never the pathname again — refusing a directory, FIFO, device node or socket with ErrNotRegular. Stating the handle rather than the path closes the window where a rename between a check and an open would let a caller decode one generation's bytes while recording another's identity as a FileIdentity.
The descriptor lets a caller stream the file through a decoder or decryptor without materializing it, which a []byte-returning helper cannot serve. For the bytes, hand the descriptor to ReadBoundedFile — that composition IS ReadBoundedInRoot. OpenRegular is the ambient-path sibling.
Errors are the filesystem's own except where this package adds a verdict: name must be relative and null-byte-free (ErrEmptyPath / ErrUnsafePath), a missing file or an escaping symlink surfaces as the root's own error, and a non-regular file is ErrNotRegular naming the actual mode. No context parameter (matching OpenParentInRoot): an open is one syscall, and a caller that goes on to read passes its context there.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
_ = os.WriteFile(filepath.Join(dir, "feed.json"), []byte(`{"items":[]}`), 0o600)
root, _ := os.OpenRoot(dir)
defer root.Close()
// One descriptor carries the shape check, the identity and the bytes. A
// caller streaming the file (through a decoder, a decryptor) uses f and
// never materializes it; this one reads it under a cap.
f, info, err := atomicfile.OpenRegularInRoot(root, "feed.json")
if err != nil {
return
}
defer f.Close()
// The FileInfo came from the descriptor the bytes come from, so recording
// it needs no second stat of the pathname.
id := atomicfile.Identify(info)
data, _ := atomicfile.ReadBoundedFile(context.Background(), f, 1<<20)
fmt.Println(len(data), id.Recorded())
}
Output: 12 true
func OpenRegularInRootNoFollow ¶ added in v3.1.0
OpenRegularInRootNoFollow is OpenRegularInRoot with the opposite link policy: it REFUSES a symlink at the final component instead of resolving it. Same returns and same ownership, and the same ErrNotRegular verdict for a directory, FIFO, device node or socket.
A second function rather than an option on the first, because the permissive answer must not be reachable by omission: a policy type has a zero value, and a zero value meaning "follow" is a guarantee lost by forgetting a field.
O_NOFOLLOW IS NOT THE MECHANISM, measured rather than assumed: os.Root resolves in-root symlinks itself before opening the final component, so the flag is silently inert through Root.OpenFile (go1.27.1 — the symlink opens and yields the target's bytes with it set). Root.Lstat's answer is the refusal instead, and the descriptor's identity is confirmed against it so a name repointed in between is ErrRaced rather than passed off as the file that was checked. A hard link to the same inode compares equal, correctly.
Errors: ErrEmptyPath or ErrUnsafePath for an empty, NUL-holding or absolute name; ErrSymlinkTarget for a symlink; ErrRaced for a mid-sequence change; *NotRegularError (matching ErrNotRegular) carrying the mode; the root's own error otherwise. Like its sibling it does not pin the ANCESTOR components — OpenParentInRoot is the primitive for that.
func ReadBounded ¶
ReadBounded opens path, validates its size against maxBytes, and reads it via an io.LimitReader. Returns ErrFileTooLarge if the file exceeds maxBytes, including if it grows past the limit during the read. ctx is checked before the open and before the read.
Unlike the write primitives, ReadBounded does NOT refuse symlink targets: os.Open follows symlinks. Callers reading from a directory writable by a less-trusted principal should confine the path themselves: open through an *os.Root and read with ReadBoundedFile.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, "data.txt")
_ = os.WriteFile(path, []byte("bounded"), 0o644)
data, _ := atomicfile.ReadBounded(context.Background(), path, 1<<20)
fmt.Println(string(data))
}
Output: bounded
func ReadBoundedFile ¶
ReadBoundedFile reads up to maxBytes from an already-open file, applying the same size validation as ReadBounded: returns ErrFileTooLarge if the file exceeds maxBytes, including if it grows past the limit during the read. ctx is checked before the size stat and before the read. The caller owns f; ReadBoundedFile does not close it.
This is the seam for a caller that must open the file itself, most notably through an *os.Root to confine the path, which ReadBounded cannot do because os.Open follows symlinks.
func ReadBoundedInRoot ¶
func ReadBoundedInRoot(ctx context.Context, root *os.Root, name string, maxBytes int64) ([]byte, error)
ReadBoundedInRoot opens name inside root and reads it under maxBytes, confining the read to root's tree: a symlink or ".." component in name can never redirect it outside (Go 1.24+ *os.Root). It is the read-side counterpart to WriteFileInRoot.
Only regular files are read. A named pipe, device node or socket planted in the tree is rejected, and the open is non-blocking so a FIFO with no writer cannot stall the caller indefinitely.
This is exactly the composition of OpenRegularInRoot and ReadBoundedFile; a caller needing the descriptor itself — to stream the file, or to record its FileInfo alongside the bytes — takes the two apart instead.
The caller owns root; ReadBoundedInRoot does not close it.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
_ = os.WriteFile(filepath.Join(dir, "cert.pem"), []byte("-----BEGIN..."), 0o600)
// A root confines every read to this tree: a symlink or ".." in the name cannot
// redirect the read outside it.
root, _ := os.OpenRoot(dir)
defer root.Close()
data, _ := atomicfile.ReadBoundedInRoot(context.Background(), root, "cert.pem", 1<<20)
fmt.Println(len(data))
}
Output: 13
func RemoveFileInRoot ¶
RemoveFileInRoot removes the regular file at name inside root, unlinking it through a parent directory pinned by OpenParentInRoot so no ancestor component can redirect the removal at another file. It is the removal counterpart to WriteFileInRoot.
Only a regular file is removed. A directory, symlink, device node, socket or named pipe wearing the name is refused with ErrNotRegular and left as found — the same rule ReadBoundedInRoot applies to what it reads. Removing a symlink itself, or an empty directory, is not this function's job; use the pinned root from OpenParentInRoot for that.
A missing file is reported (matching fs.ErrNotExist) rather than swallowed. The caller owns root; RemoveFileInRoot does not close it.
Example ¶
package main
import (
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
_ = os.MkdirAll(filepath.Join(dir, "example.com"), 0o750)
_ = os.WriteFile(filepath.Join(dir, "example.com", "cert.pfx"), []byte("bundle"), 0o600)
root, _ := os.OpenRoot(dir)
defer root.Close()
// The unlink runs through a parent directory pinned component by component, so
// an ancestor swapped for a symlink cannot redirect it at another file in the
// tree — which a plain root.Remove of this same name would allow.
err := atomicfile.RemoveFileInRoot(root, "example.com/cert.pfx")
_, statErr := os.Lstat(filepath.Join(dir, "example.com", "cert.pfx"))
fmt.Println(err, os.IsNotExist(statErr))
}
Output: <nil> true
func TempName ¶
func TempName() string
TempName returns a fresh temp base name of the exact shape this package creates and IsPackageTemp recognises, drawn from crypto/rand.
Use it when a caller must create its own file in a directory this package sweeps and wants the sweep to reclaim it. Nothing is created; two calls can be used for two files.
A collision with an existing file is possible in principle and not handled here: a caller creating the file with O_EXCL learns about it and can ask again, the way createTempInRoot does internally.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"time"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
// A caller staging its own file in a directory this package sweeps takes
// the name from TempName instead of rebuilding the convention, so an
// orphan is reclaimed like any other temp.
path := filepath.Join(dir, atomicfile.TempName())
_ = os.WriteFile(path, []byte("mine"), 0o600)
old := time.Now().Add(-2 * time.Hour)
_ = os.Chtimes(path, old, old)
res, _ := atomicfile.CleanupStaleTemps(context.Background(), dir, time.Hour)
fmt.Println(atomicfile.IsPackageTemp(filepath.Base(path)), res.Removed)
}
Output: true 1
func ValidatePath ¶
ValidatePath checks path against the rule this package's absolute-path entry points apply (WriteFile, WriteReader, NewPendingFile, ReadBounded), returning nil when acceptable and otherwise ErrEmptyPath or ErrUnsafePath — the exported face of validateAbsClean, so acceptance here and a later write's rejection cannot drift apart.
Unlike filepath.IsAbs, this also rejects an embedded NUL byte, matching what every write here refuses. Nothing on the filesystem is consulted: nil means the path is well formed, not that a write there will succeed (ProbeWritable answers that by actually writing).
Being absolute is not containment: filepath.Clean normalizes ".." in an absolute path, so nil says nothing about which subtree the path lands in. A caller confining writes to a directory tree uses the *os.Root-backed APIs (WriteFileInRoot / WriteReaderInRoot).
func WalkDirInRoot ¶
WalkDirInRoot enumerates root's tree and hands every entry to fn, root-relative, confined to root's tree: every step is an openat-relative syscall, no ambient path is ever constructed, and a symlinked directory is never descended.
Compared to fs.WalkDir over root.FS(): entries are read in fixed batches (walkReadDirBatch) rather than one materialized+sorted inventory per directory; exactly ONE directory handle is open at a time (a queue of NAMES between directories, so descriptor use cannot exhaust on a deep tree); and each directory is opened O_DIRECTORY, so a named pipe swapped in for a directory is refused with ENOTDIR instead of blocking the calling goroutine forever in open(2).
Callback contract ¶
fn is an fs.WalkDirFunc, called exactly as fs.WalkDir calls one: the root itself first as ".", then each entry pre-order, with a directory that cannot be opened or finished reported through fn for ITS OWN path (d nil, err set). fs.SkipDir and fs.SkipAll mean what they mean in fs.WalkDir. Whether a read failure below the root is fatal is the callback's call: return the error to abort, or nil to count it and continue.
Two deliberate differences from fs.WalkDir ¶
Entries arrive in DIRECTORY order, sorted only within a batch — do not build a decision on the order. A directory's own entries are all visited before the walk descends into its subdirectories.
Cancellation ¶
The walk stops between batches once ctx is done (at most one batch of entries); a caller wanting per-entry cancellation checks ctx in fn.
The caller owns root; WalkDirInRoot does not close it.
Example ¶
package main
import (
"context"
"fmt"
"io/fs"
"os"
"path/filepath"
"strings"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
_ = os.MkdirAll(filepath.Join(dir, "example.com"), 0o750)
_ = os.WriteFile(filepath.Join(dir, "example.com", "cert.pfx"), []byte("bundle"), 0o600)
// A symlinked directory is reported and never descended, so nothing is
// enumerated under a path whose ancestors do not physically hold it.
_ = os.Symlink("example.com", filepath.Join(dir, "alias"))
root, _ := os.OpenRoot(dir)
defer root.Close()
var found []string
_ = atomicfile.WalkDirInRoot(context.Background(), root, func(rel string, d fs.DirEntry, err error) error {
if err != nil {
// A sub-path the walk cannot enter: count it and carry on with the
// rest of the tree, or return the error to abort.
return nil
}
if !d.IsDir() && strings.HasSuffix(rel, ".pfx") {
found = append(found, rel)
}
return nil
})
fmt.Println(found)
}
Output: [example.com/cert.pfx]
Types ¶
type FileIdentity ¶
type FileIdentity struct {
// contains filtered or unexported fields
}
FileIdentity records WHICH generation of a file a reader currently holds, so a cache can answer "is what I loaded still what is on disk?" from a stat alone, without re-reading the bytes.
Matches compares mtime equality AND os.SameFile identity, and both legs are load-bearing: an IN-PLACE writer keeps the same inode but may not advance the mtime (inode times come from a coarse clock tick, so two writes inside one tick can share an mtime), while a PUBLISH-BY-RENAME writer (every write in this package) installs a different inode but can carry an OLD timestamp forward (a backup restore, rsync -t). Neither leg alone catches both cases. Size is a third leg this type does not hold: it is what catches an in-place rewrite that changes the file's LENGTH without advancing its mtime; a caller whose file may be rewritten in place should keep its own size comparison beside Changed.
The zero value records nothing, which reports Changed — the fail direction a cache wants, since a spurious reload costs one read while a missed reload serves stale data indefinitely.
FileIdentity is a comparison primitive, not a policy: what to do about a changed file, and when to re-stat, stay with the caller.
func Identify ¶
func Identify(info os.FileInfo) FileIdentity
Identify captures the identity of the file described by info, as returned by os.Stat, os.Lstat, or (*os.File).Stat. A nil info records nothing, so the result reports Changed against every later stat.
func (FileIdentity) Changed ¶
func (id FileIdentity) Changed(info os.FileInfo) bool
Changed is the negation of Matches, for the reload-side reading: it reports whether info is a file generation this identity did not capture, and so whether a reader holding the captured generation must load again.
func (FileIdentity) Matches ¶
func (id FileIdentity) Matches(info os.FileInfo) bool
Matches reports whether info describes the same file generation this identity captured: an equal modification time AND the same file (os.SameFile, which compares the underlying device and inode). An unrecorded identity matches nothing, and a nil info — no file observed — matches nothing.
func (FileIdentity) ModTime ¶
func (id FileIdentity) ModTime() time.Time
ModTime returns the captured modification time, or the zero Time when nothing was recorded. For diagnostics only; Matches owns the freshness test, since mtime alone is not sufficient.
func (FileIdentity) Recorded ¶
func (id FileIdentity) Recorded() bool
Recorded reports whether an identity was captured at all. A zero FileIdentity (nothing loaded yet, or a load that failed before its stat) records nothing.
type NotRegularError ¶ added in v3.1.0
type NotRegularError struct {
// Name is the path or root-relative name as the caller supplied it, cleaned.
Name string
// Mode is the full FileMode of what was actually there. Type() names the
// kind; the permission bits are kept because a caller reporting an
// unexpected object usually wants both.
Mode os.FileMode
}
NotRegularError reports that a name resolved to something other than a regular file, and carries the mode that decided it.
The mode is a DIAGNOSTIC a caller reports, and reading it out of a message string is not something a caller should have to do. Every producer here returns one, so a caller resolving a name once never has to stat the path a second time just to describe a refusal. It unwraps to ErrNotRegular, so errors.Is keeps matching for callers that only need the verdict.
func (*NotRegularError) Error ¶ added in v3.1.0
func (e *NotRegularError) Error() string
func (*NotRegularError) Unwrap ¶ added in v3.1.0
func (e *NotRegularError) Unwrap() error
type Option ¶
type Option func(*cfg)
Option configures an atomic write, a stale-temp sweep, or EnsurePrivateDir. Each option's doc names which operations it applies to; the rest ignore it.
func WithLogger ¶
WithLogger sets a custom logger. If not provided, slog.Default() is used.
func WithMaxBytes ¶
WithMaxBytes caps the content size an atomic write will stage: the write-side mirror of ReadBounded's bound, so a writer that also owns the reader can refuse to persist a file its own read path would refuse to load. WriteFile/WriteFileInRoot reject over-cap content before the temp is created; WriteReader/WriteReaderInRoot reject the copy chunk that would cross the cap; a PendingFile rejects the Write/WriteString/ReadFrom call that would cross it, whole (see PendingFile.Write). The barrier also verifies the staged file's actual size before publication, so bytes staged outside those interfaces (WriteAt, Write after Seek) cannot publish an over-cap file. Every rejection matches ErrFileTooLarge and leaves the previous file at the target path intact. n <= 0 means no cap (the default).
func WithMkdirMode ¶
WithMkdirMode creates the parent directory (and any missing ancestors) with the given permission before writing; without it a missing parent is an error. Applies to every write entry point; sweeps and EnsurePrivateDir ignore it.
The mode is ENFORCED on each created directory, not merely requested: mkdir(2) passes it through umask, and measured under umask 077 a requested 0o755 stored 0o700. A filesystem that won't store the mode fails the write with ErrModeNotStored. A PRE-EXISTING directory is never chmod'ed.
Each created directory's parent is fsynced as it is made; Result.Durable is false if any of those fsyncs failed, but the write still succeeds.
func WithRecursive ¶
WithRecursive controls whether a stale-temp sweep descends into subdirectories, or sweeps only the named directory. Affects CleanupStaleTemps and CleanupStaleTempsInRoot; every write entry point ignores it.
Descent is not the default because a sweep is destructive, so how much of the tree it touches must be stated at the call site. Pass true when temps can be staged below the named directory — a temp is created in the SAME directory as its final target, so a write to out/example.com/cert.pfx leaves its orphan in out/example.com, invisible to a flat sweep of out/.
func WithRepairOwnedDir ¶
WithRepairOwnedDir controls whether EnsurePrivateDir repairs a PRE-EXISTING directory's mode instead of refusing it with ErrModeTooOpen. Affects EnsurePrivateDir only; every write entry point ignores it.
Repair is sound because EnsurePrivateDir already established ownership (a directory that fstats as owned by the effective uid was made by this uid, not planted by a neighbour): repairing it just re-applies the caller's own mode after a filesystem widened it (e.g. an inheritable ACL). Every other refusal (ErrNotOwned, ErrNotDirectory, the symlink refusal) still fires first.
Repair is NOT the default because a wide mode on an owned directory can be deliberate rather than drift (seadex-scout's report directory is intentionally left readable). Repaired reports whether a repair happened.
type PendingFile ¶
PendingFile is a temp file open for writing, destined to atomically replace a target on Commit. It embeds *os.File, so callers get the full io.Writer/io.ReaderFrom/fmt.Fprintf surface, and the embedded Name() reports the temp's path so the staged file can be handed to external verifiers before Commit.
A PendingFile is written as an append-only stream: Write, WriteString, and ReadFrom maintain a byte count (BytesWritten) that Truncate re-syncs, and a WithMaxBytes cap is enforced on exactly that stream. Operations on the embedded *os.File that step outside the stream model (WriteAt, Write after Seek) bypass the accounting, but not the cap: Commit re-verifies the staged file's actual size against the cap at the durability barrier.
Every filesystem operation runs through an *os.Root: the caller's root for NewPendingFileInRoot, or a root of the target's parent directory that NewPendingFile opens and owns. An owned root is closed when the PendingFile reaches a terminal state (Commit called, or Cleanup succeeded).
A PendingFile is not safe for concurrent use: Commit and Cleanup mutate unsynchronized lifecycle state. Confine each PendingFile to a single goroutine.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, "pending.txt")
pf, _ := atomicfile.NewPendingFile(context.Background(), path)
defer func() { _ = pf.Cleanup() }()
_, _ = pf.Write([]byte("incremental"))
_, _ = pf.Commit(context.Background())
data, _ := os.ReadFile(path)
fmt.Println(string(data))
}
Output: incremental
func NewPendingFile ¶
NewPendingFile creates a temp file destined to atomically replace path. Write to it, then call Commit to finalize or Cleanup to abort. Mode defaults to 0o644 (override with WithMode). ctx is checked before the temp is created.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, "pending.txt")
pf, _ := atomicfile.NewPendingFile(context.Background(), path)
defer func() { _ = pf.Cleanup() }()
_, _ = pf.Write([]byte("incremental"))
res, _ := pf.Commit(context.Background())
data, _ := os.ReadFile(res.Path)
fmt.Println(string(data))
}
Output: incremental
func NewPendingFileInRoot ¶
func NewPendingFileInRoot(ctx context.Context, root *os.Root, name string, opts ...Option) (*PendingFile, error)
NewPendingFileInRoot creates a temp file destined to atomically replace name, a path relative to root, with the same confinement as WriteFileInRoot. Write to the returned PendingFile, then call Commit to finalize or Cleanup to abort; the lifecycle is identical to NewPendingFile. Mode defaults to 0o644 (override with WithMode). A nil root returns ErrUnsafePath.
The caller owns root and must keep it open for the PendingFile's lifetime; the PendingFile never closes a caller-provided root. Result.Path is root's directory joined with the cleaned relative name.
Example ¶
package main
import (
"context"
"fmt"
"os"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
root, _ := os.OpenRoot(dir)
defer func() { _ = root.Close() }()
// The pending temp and its eventual rename are confined to the root's
// tree; the caller keeps ownership of the root.
pf, _ := atomicfile.NewPendingFileInRoot(context.Background(), root, "staged.txt")
defer func() { _ = pf.Cleanup() }()
_, _ = pf.Write([]byte("confined incremental"))
res, _ := pf.Commit(context.Background())
data, _ := os.ReadFile(res.Path)
fmt.Println(string(data))
}
Output: confined incremental
func (*PendingFile) BytesWritten ¶
func (p *PendingFile) BytesWritten() int64
BytesWritten reports the staged file's size under the append-stream model: bytes accepted through Write, WriteString, and ReadFrom, re-synced by Truncate. Operations on the embedded *os.File that step outside the stream model are not tracked; a WithMaxBytes cap still catches them at Commit, which verifies the staged file's actual size.
func (*PendingFile) Cleanup ¶
func (p *PendingFile) Cleanup() error
Cleanup closes and removes the temp file, aborting the pending write. It is a no-op once Commit has been called. After a successful Cleanup, a subsequent Commit returns ErrAborted.
If the temp removal fails for a reason other than the file already being gone, Cleanup returns that error WITHOUT marking the write cleaned, so a later Cleanup retries the removal. Safe to defer immediately after NewPendingFile.
func (*PendingFile) Commit ¶
func (p *PendingFile) Commit(ctx context.Context) (Result, error)
Commit runs the durability barrier (WithMaxBytes size verification, chmod, fsync, close), atomically renames the temp into place, and fsyncs the parent directory. Commit is idempotent: repeated calls return the first result. Calling Commit after Cleanup returns ErrAborted. After a successful Commit, Cleanup is a no-op. ctx is checked through the temp-side barrier; a context cancelled at or before close aborts and removes the temp. Once the barrier passes, the rename runs without a further ctx check, so a context cancelled in the narrow window between close and rename still commits.
func (*PendingFile) ReadFrom ¶
func (p *PendingFile) ReadFrom(r io.Reader) (int64, error)
ReadFrom streams r into the staged temp. With a WithMaxBytes cap set it routes every chunk through Write; uncapped it delegates to the embedded *os.File's ReadFrom (keeping the OS copy fast path) and records the copied size.
func (*PendingFile) Truncate ¶
func (p *PendingFile) Truncate(size int64) error
Truncate resizes the staged temp and re-syncs the byte accounting to the new size. Growing the file beyond a WithMaxBytes cap is rejected with an error matching ErrFileTooLarge.
func (*PendingFile) Write ¶
func (p *PendingFile) Write(b []byte) (int, error)
Write stages p, enforcing the WithMaxBytes cap when one is set: a write that would cross the cap is rejected whole with an error matching ErrFileTooLarge. Accepted bytes advance BytesWritten.
func (*PendingFile) WriteString ¶
func (p *PendingFile) WriteString(s string) (int, error)
WriteString applies the same WithMaxBytes cap and byte accounting as Write (the embedded *os.File's own WriteString would bypass both).
type PrivateDir ¶
type PrivateDir struct {
// Mode is the mode the filesystem actually stored, read back from the
// open handle (permission bits plus setuid/setgid/sticky). Always
// privateDirMode when the error is nil, except on the
// pre-existing-and-already-private path, where it is what was found.
Mode os.FileMode
// Created reports whether THIS call created the directory — the field
// the repair decision turns on: a directory this process just made is
// one no other writer has ever held a name to.
Created bool
// Repaired reports whether the mode had to be corrected because the
// filesystem did not store what was asked (e.g. an inheritable ACL
// widening a fresh 0700 directory). Unconditional on a Created
// directory; on a pre-existing one, only under WithRepairOwnedDir.
Repaired bool
}
PrivateDir reports the outcome of one EnsurePrivateDir call.
Only meaningful alongside a nil error: a non-nil error means no verdict was reached, which is NOT "nothing happened" — the mkdir may have succeeded and a later step refused the result, so the directory can exist while its custody is unestablished. Treat a failure as fatal; do not retry into it.
func EnsurePrivateDir ¶
func EnsurePrivateDir(dir string, opts ...Option) (PrivateDir, error)
EnsurePrivateDir establishes custody of ONE directory level that only this process's user may enter: it creates dir 0700 if absent, then proves from an open handle that what is now at that path is a real directory, owned by the effective uid, with no group or other access.
dir's own parent is not created, inspected, or vouched for; a multi-level path is the caller's own loop, outermost first. os.MkdirAll cannot substitute: it follows a symlink and cannot tell "I created this" from "something was already here", which the decisions below turn on.
The sequence and why each step matters: mkdir(2) at 0700, recording whether THIS call created the level (fs.ErrExist means it did not). Open the result O_DIRECTORY|O_NOFOLLOW|O_RDONLY — the kernel refuses a planted symlink or non-directory rather than following it, and a planted FIFO cannot stall the caller in open(2). fstat(2) the handle so every later check reads the descriptor, never the pathname. Require the owner uid to equal os.Geteuid() — a level owned by somebody else can be renamed or replaced after the verdict returns, so mode alone is not enough. If THIS call created the level, EnforceMode it to 0700 (safe because mkdir just proved nobody else ever held that name). If the level PRE-EXISTED, it is never chmod'ed — repairing another principal's directory would take over their name — and is instead refused if any group or other bit is set (ErrModeTooOpen).
The verdict is POINT-IN-TIME: it proves what was true of one inode while a handle was open, and does NOT pin the directory for later use. A caller that then does ReadDir/Remove/Open/Mkdir through the PATHNAME re-resolves every component and re-opens the window this closed. Closing that gap needs a retained handle (an *os.Root) instead of a name — a different API shape neither current consumer needs.
Errors: ErrEmptyPath/ErrUnsafePath for an empty, NUL-bearing, or non-absolute dir; ErrSymlinkTarget for a symlink at the final component; ErrNotDirectory for a plain file, FIFO, device node or socket; ErrNotOwned for a foreign owner; ErrModeTooOpen for a pre-existing directory with group or other access; ErrModeNotStored when the filesystem refuses to store 0700 on a directory this call created. Everything else is the filesystem's own error. Match with errors.Is.
WithRepairOwnedDir decides the pre-existing too-open case above; WithLogger supplies the logger for the one Warn a mode repair emits. Every other Option is ignored — the mode is not a parameter.
Example ¶
package main
import (
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
base, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(base)
// One call establishes ONE level, so a multi-level path is the caller's loop,
// outermost first: each level gets its own verdict.
root := filepath.Join(base, "app")
state := filepath.Join(root, "state")
for _, dir := range []string{root, state} {
pd, err := atomicfile.EnsurePrivateDir(dir)
if err != nil {
fmt.Println("refused:", err)
return
}
fmt.Printf("%s created=%t mode=%#o\n", filepath.Base(dir), pd.Created, pd.Mode)
}
// A second run adopts what the first one left, and never chmods it.
pd, _ := atomicfile.EnsurePrivateDir(state)
fmt.Printf("second run created=%t mode=%#o\n", pd.Created, pd.Mode)
}
Output: app created=true mode=0700 state created=true mode=0700 second run created=false mode=0700
Example (Refusals) ¶
package main
import (
"errors"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
base, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(base)
// A symlink planted at the name is refused by the kernel, not followed.
link := filepath.Join(base, "link")
_ = os.Symlink(base, link)
_, err := atomicfile.EnsurePrivateDir(link)
fmt.Println("symlink:", errors.Is(err, atomicfile.ErrSymlinkTarget))
// A pre-existing directory somebody else could enter is refused, never
// repaired: chmod'ing another principal's directory would take over its name.
shared := filepath.Join(base, "shared")
_ = os.Mkdir(shared, 0o755)
_ = os.Chmod(shared, 0o755)
_, err = atomicfile.EnsurePrivateDir(shared)
fmt.Println("group/other access:", errors.Is(err, atomicfile.ErrModeTooOpen))
}
Output: symlink: true group/other access: true
type ProbeResult ¶
type ProbeResult struct {
// Err is the failure from Stage, unwrapped to the underlying filesystem
// error so errors.Is against fs.ErrPermission, fs.ErrNotExist or
// syscall.ENOSPC works. It is nil exactly when OK reports true.
Err error
// Dir is the directory that was probed: the cleaned argument for
// ProbeWritable, or root.Name() joined with the cleaned relative name for
// ProbeWritableInRoot (the Result.Path convention).
Dir string
// Name is the probe file's base name once it was created, and "" when the
// probe never got that far. It always satisfies IsPackageTemp, so a
// leftover is reclaimable by CleanupStaleTemps.
Name string
// Stage is the first stage that failed, or ProbeStageNone when all passed.
Stage ProbeStage
// Leaked reports whether the probe file is still on disk. It can be true
// only alongside ProbeStageRemove, or alongside ProbeStageWrite,
// ProbeStageSync or ProbeStageClose when the follow-up unlink also failed
// (that secondary error is logged at Debug, since Err holds the first and
// more informative failure).
Leaked bool
}
ProbeResult reports the outcome of one directory writability probe.
It is an outcome record, not an error: a stage failure arrives here, never as the probe function's error return, so the caller decides which stages are fatal. A caller that wants pass/fail asks OK once.
func ProbeWritable ¶
ProbeWritable proves dir is genuinely writable by doing what a real atomic write does — create a temp file, write and flush a byte, close it, unlink it — and reporting which stage failed.
A mode-bit stat lies on an NFS/FUSE mount, a read-only bind mount, or a Docker volume owned by another UID; this exercises the real path instead.
`err != nil` means the probe could not be attempted at all (empty dir, or a done context), never "not writable" — every filesystem outcome is reported in the ProbeResult. See ProbeStage and ProbeResult.Writable.
The probe file carries this package's temp-name shape (TempName), so a leftover from a crash or a denied unlink is reclaimed by CleanupStaleTemps.
A missing dir fails at ProbeStageCreate; pass WithMkdirMode for ProbeStageMkdir instead. dir may be relative, matching CleanupStaleTemps rather than the write functions' absolute-path contract.
ctx is checked once, before anything is created; a probe that has begun always runs its own cleanup rather than abandoning a file.
Example ¶
package main
import (
"context"
"fmt"
"os"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
res, err := atomicfile.ProbeWritable(context.Background(), dir)
if err != nil {
return // the probe could not be attempted (empty dir, cancelled ctx)
}
// The stage decides the policy, not the library: this caller refuses to
// start when the directory cannot take a write, and only warns when the
// write worked but the probe file could not be cleaned up.
switch {
case !res.Writable():
fmt.Println("not writable:", res.Stage, res.Err)
case !res.OK():
fmt.Println("writable, but cleanup failed:", res.Stage, "leaked:", res.Leaked)
default:
fmt.Println("writable, nothing left behind")
}
// The probe file carries this package's temp shape, so a leaked one is
// reclaimed by CleanupStaleTemps.
fmt.Println(atomicfile.IsPackageTemp(res.Name))
}
Output: writable, nothing left behind true
func ProbeWritableInRoot ¶
func ProbeWritableInRoot(ctx context.Context, root *os.Root, name string, opts ...Option) (ProbeResult, error)
ProbeWritableInRoot is ProbeWritable confined to root's tree: name is relative to root ("." for root itself), and every operation runs through the *os.Root, so a symlink or ".." component cannot escape it. An escaping name is refused and reported as ProbeStageCreate (or ProbeStageMkdir under WithMkdirMode).
Outcome model, options, cancellation and reclaimability are identical to ProbeWritable. The caller owns root; ProbeWritableInRoot does not close it. A nil root returns ErrUnsafePath.
Example ¶
package main
import (
"context"
"fmt"
"os"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
root, _ := os.OpenRoot(dir)
defer func() { _ = root.Close() }()
// Probing through the root a caller already holds checks the same object
// its writes will use; "." is the root itself.
res, _ := atomicfile.ProbeWritableInRoot(context.Background(), root, ".")
fmt.Println(res.OK(), res.Leaked)
// An escaping name is refused by the root, reported as a stage failure.
escaped, _ := atomicfile.ProbeWritableInRoot(context.Background(), root, "../outside")
fmt.Println(escaped.Stage, escaped.Writable())
}
Output: true false create probe file false
func (ProbeResult) Writable ¶
func (r ProbeResult) Writable() bool
Writable reports whether the directory accepted a real write — created, written and flushed — so at worst only teardown (close, unlink) failed.
type ProbeStage ¶
type ProbeStage int
ProbeStage identifies which step of a writability probe failed, in the order a real write walks: a directory can accept the entry yet reject the first write, fail only at Sync or Close, or accept everything and deny the unlink.
The order is load-bearing: ProbeStageClose or later means real bytes were flushed and only teardown failed (see ProbeResult.Writable); the probe reports the stage and leaves the pass/fail policy to the caller.
const ( // ProbeStageNone is the zero value: every stage passed. ProbeStageNone ProbeStage = iota // ProbeStageMkdir indicates the directory itself could not be created. // Only reachable with WithMkdirMode; without it a missing directory // fails at ProbeStageCreate, exactly as a write to a missing parent does. ProbeStageMkdir // ProbeStageCreate indicates the probe file could not be created: the // directory is missing, is not a directory, is read-only, or denies the // running UID. It also covers a name that escapes the *os.Root in // ProbeWritableInRoot. ProbeStageCreate // ProbeStageWrite indicates the first data write to the probe file failed // (a quota or a full filesystem, which the create alone does not reveal). ProbeStageWrite // ProbeStageSync indicates flushing the probe file failed, the delayed // error a network filesystem reports at fsync rather than at write. ProbeStageSync // ProbeStageClose indicates closing the probe file failed, the other // place a deferred write error surfaces. ProbeStageClose // ProbeStageRemove indicates the probe file could not be unlinked, so the // directory accepts writes but refuses cleanup. ProbeResult.Leaked is then // true and the leftover is reclaimable by the package's stale-temp sweep. ProbeStageRemove )
func (ProbeStage) String ¶
func (s ProbeStage) String() string
type Result ¶
type Result struct {
// Path is the cleaned final path the data was written to. It is
// absolute for the package-level write functions; for the *InRoot
// functions it is root.Name() joined with the cleaned relative name.
Path string
// Durable reports whether the write is guaranteed to survive a crash:
// true only when the file and every directory its path depends on were
// fsynced. False means the data is present at Path but may not survive
// an immediate power loss, and the failure is logged at Warn.
Durable bool
}
Result reports the outcome of an atomic write that reached its final path.
func WriteFile ¶
WriteFile atomically writes data to path. Mode defaults to 0o644 (override with WithMode). A nil error means the data is at path; check Result.Durable for crash durability.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, "data.txt")
res, _ := atomicfile.WriteFile(context.Background(), path, []byte("hello"))
data, _ := os.ReadFile(path)
fmt.Println(string(data), res.Durable)
}
Output: hello true
Example (WithMkdirMode) ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, "nested", "dir", "file.txt")
_, _ = atomicfile.WriteFile(context.Background(), path, []byte("deep"),
atomicfile.WithMkdirMode(0o755))
data, _ := os.ReadFile(path)
fmt.Println(string(data))
}
Output: deep
Example (WithMode) ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, "secret.txt")
_, _ = atomicfile.WriteFile(context.Background(), path, []byte("s3cr3t"),
atomicfile.WithMode(0o600))
fi, _ := os.Stat(path)
fmt.Println(fi.Mode().Perm())
}
Output: -rw-------
func WriteFileInRoot ¶
func WriteFileInRoot(ctx context.Context, root *os.Root, name string, data []byte, opts ...Option) (Result, error)
WriteFileInRoot atomically writes data to name, a path relative to root, with the same temp-then-rename durability and symlink refusal as WriteFile but confined to root: every filesystem operation runs through the *os.Root (Go 1.24+), so a symlink or ".." component in name can never write outside root's tree. Mode defaults to 0o644 (override with WithMode). A nil error means the data is at name; check Result.Durable for crash durability. Result.Path is root's directory joined with the cleaned relative name. A nil root returns ErrUnsafePath.
Example ¶
package main
import (
"context"
"fmt"
"os"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
root, _ := os.OpenRoot(dir)
defer func() { _ = root.Close() }()
// name is relative to the root; a symlink or ".." in it cannot escape the
// root's tree (Go 1.24+).
_, _ = atomicfile.WriteFileInRoot(context.Background(), root, "rooted.txt",
[]byte("confined"))
f, _ := root.Open("rooted.txt")
defer func() { _ = f.Close() }()
data, _ := atomicfile.ReadBoundedFile(context.Background(), f, 1<<20)
fmt.Println(string(data))
}
Output: confined
func WriteReader ¶
WriteReader atomically writes the contents of r to path. Mode defaults to 0o644 (override with WithMode). If r implements io.WriterTo it is used for efficient copying, so cancellation is coarse on that path (per-chunk for chunked sources, post-copy for single-shot sources). ctx is still honored at the durability barrier, so a cancelled write leaves no partial target.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"strings"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, "stream.txt")
_, _ = atomicfile.WriteReader(context.Background(), path,
strings.NewReader("streamed"), atomicfile.WithMode(0o600))
data, _ := os.ReadFile(path)
fmt.Println(string(data))
}
Output: streamed
Example (WithMode) ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"strings"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, "stream.txt")
_, _ = atomicfile.WriteReader(context.Background(), path,
strings.NewReader("streamed"), atomicfile.WithMode(0o644))
data, _ := os.ReadFile(path)
fmt.Println(string(data))
}
Output: streamed
func WriteReaderInRoot ¶
func WriteReaderInRoot(ctx context.Context, root *os.Root, name string, r io.Reader, opts ...Option) (Result, error)
WriteReaderInRoot atomically writes the contents of r to name, a path relative to root, confined to root's tree (see WriteFileInRoot). If r implements io.WriterTo it is used for efficient copying, so cancellation is coarse on that path. Mode defaults to 0o644 (override with WithMode). A nil root returns ErrUnsafePath.
type SweepResult ¶
type SweepResult struct {
// Removed counts temps reclaimed.
Removed int
// Failed counts candidates that could not be inspected or unlinked.
Failed int
// Unreadable counts sub-paths the walk could not enter.
Unreadable int
}
SweepResult is the per-outcome accounting of one stale-temp sweep, returned by both CleanupStaleTemps and CleanupStaleTempsInRoot.
Failed and Unreadable are separate because they are different operator problems. Failed means a temp was found and could not be reclaimed (permissions on the file, or an IO error) — orphans are accumulating. Unreadable means a subdirectory could not be entered at all, so it may be hiding orphans nobody has counted. A caller that folds them together cannot tell an operator which one to go fix.
func CleanupStaleTemps ¶
func CleanupStaleTemps(ctx context.Context, dir string, maxAge time.Duration, opts ...Option) (SweepResult, error)
CleanupStaleTemps removes temp files in dir that this package created (".atomicfile-<digits>.tmp") and whose mtime is older than maxAge, reporting the per-outcome counts. A missing dir is not an error.
It is the ambient-path sibling of CleanupStaleTempsInRoot and differs from it in exactly one property: every path is built with filepath.Join and handed to os.Lstat/os.Remove, which is safe for a directory the caller owns outright and NOT safe for one a co-mounting writer can modify underneath. Reach for the root-confined form there; reconstructing an ambient path and calling this reintroduces precisely that TOCTOU window.
Depth is opt-in through WithRecursive, identically for both, because a sweep deletes files and how much of the filesystem it touches belongs at the call site.
Cancellation. The walk stops between entries once ctx is done, so a sweep of a large tree cannot hold up shutdown, and an already-cancelled context does no work. A cancelled sweep returns ctx.Err() alongside the counts accumulated so far.
Best-effort per file: an individual stat or remove failure is logged at Debug and counted in SweepResult.Failed rather than returned, and a subdirectory that cannot be entered is counted in Unreadable. Only a failure to read dir itself is returned.
Choosing maxAge ¶
maxAge must exceed the longest time any CONCURRENT writer may hold a temp, because a sweep cannot tell an orphan from a write in progress — POSIX offers no way to ask. The gate is the temp's mtime, not its creation time, so a streaming write that keeps producing bytes keeps refreshing it and is safe at any duration; what is at risk is a temp nothing has written to for maxAge. The realistic case is a PendingFile: a caller that stages, then does slow work, then Commits. _Measured_: with a temp backdated past a one-hour maxAge, the sweep unlinked it and the subsequent Commit failed with *WriteError{PhaseRename} wrapping ENOENT. No data is lost (the previous file at the target is untouched) but that write is.
A non-positive maxAge skips the sweep with a Warn rather than reaping everything, so a zero value from an unset config cannot empty a directory.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"time"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
// Simulate an orphaned temp left by an interrupted write.
stale := filepath.Join(dir, ".atomicfile-123456.tmp")
_ = os.WriteFile(stale, []byte("partial"), 0o644)
old := time.Now().Add(-2 * time.Hour)
_ = os.Chtimes(stale, old, old)
res, _ := atomicfile.CleanupStaleTemps(context.Background(), dir, time.Hour)
fmt.Println(res.Removed)
}
Output: 1
func CleanupStaleTempsInRoot ¶
func CleanupStaleTempsInRoot(ctx context.Context, root *os.Root, maxAge time.Duration, opts ...Option) (SweepResult, error)
CleanupStaleTempsInRoot removes temp files orphaned by an interrupted atomic write, confined to root's tree.
It sweeps ONE directory by default, exactly as CleanupStaleTemps does; pass WithRecursive(true) to descend. The two functions have the same signature shape and the same outcome model, and differ in exactly one property — confinement, named below. Neither differs in how much of the filesystem it touches: that is the caller's explicit choice for both, because the operation deletes files.
Confinement. Every stat and unlink goes through the *os.Root, so a symlink planted under the swept tree cannot redirect a removal outside it, and each candidate is unlinked through a PINNED parent directory (OpenParentInRoot), so an ancestor directory swapped for a symlink cannot redirect it at another file INSIDE the tree either. The ambient variant builds paths with filepath.Join and calls os.Lstat/os.Remove on them, which is safe for a directory the caller owns outright and not safe for one a co-mounting writer can modify underneath — reconstructing an ambient path and handing it to CleanupStaleTemps reintroduces exactly that TOCTOU window.
Memory. The tree is enumerated through WalkDirInRoot, which reads each directory in fixed batches, so a directory holding a large or hostile inventory is not materialized (and sorted) before the sweep looks at its first entry.
Cancellation. The walk stops between entries once ctx is done, so a sweep of a large tree cannot hold up shutdown, and an already-cancelled context does no work. A cancelled sweep returns ctx.Err() alongside the counts accumulated so far.
Both sweeps report counts instead of logging aggregates: the SweepResult carries every number a caller needs to narrate the outcome itself, so a summary line here would only duplicate that in a second voice. Per-entry diagnostics (which path, which errno) still go to the configured logger at Debug, since those are details the counts cannot carry.
maxAge must be positive; a non-positive value skips the sweep with a warning rather than reaping everything. It must also exceed the longest time any CONCURRENT writer may hold a temp — a sweep cannot tell an orphan from a write in progress, and the age gate is the temp's mtime, so what is at risk is a temp nothing has written to for maxAge (a PendingFile staged and committed slowly is the realistic case; see CleanupStaleTemps for the measurement). Only names matching this package's own temp shape are candidates, so a caller-owned file is never removed.
The caller owns root; CleanupStaleTempsInRoot does not close it.
Example ¶
package main
import (
"context"
"fmt"
"os"
"path/filepath"
"time"
"github.com/cplieger/atomicfile/v3"
)
func main() {
dir, _ := os.MkdirTemp("", "example")
defer os.RemoveAll(dir)
// An orphaned temp left by an interrupted write, in a NESTED directory: temps are
// staged next to their target, so only a recursive sweep finds this one.
nested := filepath.Join(dir, "example.com")
_ = os.MkdirAll(nested, 0o750)
stale := filepath.Join(nested, ".atomicfile-123456.tmp")
_ = os.WriteFile(stale, []byte("partial"), 0o600)
old := time.Now().Add(-2 * time.Hour)
_ = os.Chtimes(stale, old, old)
root, _ := os.OpenRoot(dir)
defer root.Close()
res, _ := atomicfile.CleanupStaleTempsInRoot(context.Background(), root, time.Hour, atomicfile.WithRecursive(true))
fmt.Println(res.Removed, res.Failed, res.Unreadable)
}
Output: 1 0 0
type WriteError ¶
type WriteError struct {
Err error
Phase WritePhase
}
WriteError wraps a hard atomic-write failure with the phase that failed. A WriteError always means the data did NOT reach its final path.
func (*WriteError) Error ¶
func (e *WriteError) Error() string
func (*WriteError) Unwrap ¶
func (e *WriteError) Unwrap() error
type WritePhase ¶
type WritePhase int
WritePhase identifies which step of an atomic write failed. Each value appears only on a WriteError. A parent-directory fsync failure is not in this enum; it is surfaced via Result.Durable instead.
const ( // PhaseTempCreate indicates failure opening the destination for writing: // opening the target's parent directory (the absolute-path entry points // open it as an *os.Root) or creating the temp file inside it. PhaseTempCreate WritePhase = iota + 1 // PhaseTempWrite indicates failure writing to the temp file. PhaseTempWrite // PhaseTempChmod indicates failure setting permissions on the temp file. PhaseTempChmod // PhaseTempSync indicates failure syncing the temp file. PhaseTempSync // PhaseTempClose indicates failure closing the temp file. PhaseTempClose // PhaseRename indicates failure renaming temp to the final path. PhaseRename )
func (WritePhase) String ¶
func (p WritePhase) String() string