atomicfile

package module
v4.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

README

atomicfile

Go Reference Go version Mutation

atomicfile writes files from Go so that a crash or a power loss leaves the complete old content or the complete new content, never a partial file.

It replaces the temp file, fsync and rename sequence you would otherwise write around os.WriteFile. It runs on Linux, containers included, uses only the standard library at run time, needs Go 1.27 or later and is licensed under Apache-2.0. macOS and BSD may work but are untested.

Why use it

atomicfile is built for Go services that keep state, configuration or credentials on disk and must not lose them to a crash.

  • Every write syncs the file and its parent directory, and Result.Durable reports whether every sync succeeded.
  • A nil error means the new data is at the path. Any other error leaves the old file in place, and a failure inside the write is a *WriteError naming the step that failed.
  • WithMode proves the mode the filesystem stored, so a filesystem that widens a 0600 request fails the write instead of publishing a readable file.
  • The *InRoot functions run through an *os.Root, so a symlink or .. in a name cannot leave the directory tree.
  • Writes refuse a symlink, FIFO, socket or device node at the target path.

Consider google/renameio if you also need to replace a symbolic link atomically.

Install

go get github.com/cplieger/atomicfile/v4@latest

Usage

package main

import (
	"context"
	"log"
	"os"

	"github.com/cplieger/atomicfile/v4"
)

func main() {
	ctx := context.Background()

	// Replace a file. Result.Durable reports whether the file and its
	// directory were both synced to disk.
	res, err := atomicfile.WriteFile(ctx, "/var/lib/myapp/state.json", []byte(`{"ok":true}`))
	if err != nil {
		log.Fatal(err)
	}
	if !res.Durable {
		log.Printf("%s is written but not yet durable", res.Path)
	}

	// A credential: staged owner-only, published at exactly 0600 or not at all.
	_, err = atomicfile.WriteFile(ctx, "/var/lib/myapp/token", []byte("secret"),
		atomicfile.WithMode(0o600))
	if err != nil {
		log.Fatal(err)
	}

	// Confined to one tree: a symlink or ".." in the name cannot leave it.
	root, err := os.OpenRoot("/var/lib/myapp")
	if err != nil {
		log.Fatal(err)
	}
	defer root.Close()
	_, err = atomicfile.WriteFileInRoot(ctx, root, "cache/index.json", []byte("[]"),
		atomicfile.WithMkdirMode(0o750))
	if err != nil {
		log.Fatal(err)
	}

	// Read it back under a 1 MiB cap.
	data, err := atomicfile.ReadBoundedInRoot(ctx, root, "cache/index.json", 1<<20)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("read %d bytes", len(data))
}

To stream content, use WriteReader. To write a file piece by piece, call NewPendingFile, write to it, then Commit to publish it or Cleanup to abort. The 23 runnable examples on pkg.go.dev cover writes, reads, sweeps, probes and private directories, and go test runs them.

API

  • Writes: WriteFile, WriteReader, NewPendingFile and their *InRoot forms.
  • Reads: ReadBounded, ReadBoundedFile, ReadBoundedInRoot, OpenRegular, OpenRegularInRoot, OpenRegularInRootNoFollow.
  • Shared directory trees: WalkDirInRoot, OpenParentInRoot, RemoveFileInRoot.
  • Modes: EnforceMode, EnsurePrivateDir.
  • Temp files and checks: CleanupStaleTemps, CleanupStaleTempsInRoot, TempName, IsPackageTemp, ProbeWritable, ProbeWritableInRoot, ValidatePath, Identify.
  • Options: WithMode, WithMkdirMode, WithMaxBytes, WithLogger, WithRecursive, WithRepairOwnedDir.
  • Errors: sentinel values for errors.Is, and *WriteError and *NotRegularError for errors.As.

The full reference is on pkg.go.dev. Choosing a function says which call fits which job.

What a nil error means

Every write creates a temp file in the target's directory, writes and syncs it, renames it over the target, then syncs the directory. After a crash the path holds the complete old content or the complete new content.

A nil error means the data reached its final path. Result.Durable then says whether that content will survive a power loss. It is false when the directory sync failed after the rename, for example with an EIO from a failing disk. A crash could then still bring back the old file. The package logs a warning in that case, and a caller that needs crash durability retries the write or raises an alert. A non-nil error means the data did not reach the path, and the previous file is untouched.

Two writers on one path each publish a whole file, and the last rename wins. The package takes no lock.

A process killed before the rename leaves its temp file behind. Nothing in the package removes it on its own, so call CleanupStaleTemps at startup or on a schedule, as Orphaned temp files explains.

Durability and errors has the full sequence and every error value.

File modes

Without WithMode, atomicfile sets no mode. The file is created the way os.Create creates one, at 0666, narrowed by the umask and widened or narrowed by any ACL the directory passes on. A write that replaces an existing file gives the new file those defaults, and the old file's mode is not kept. That suits a shared tree whose permissions an operator manages, such as a media library.

Pass WithMode for any file whose readers must be restricted, such as credentials, configuration and backups. The payload is staged in a file proven owner-only, the final file is proven to hold the mode, and a filesystem that stores anything else fails the write with ErrModeNotStored.

WithMkdirMode creates missing parent directories at a mode it also proves. EnsurePrivateDir sets up one directory level that only the effective user may enter. File modes and private directories explains both.

Unsupported by design

These are deliberate non-goals, not missing features.

  • Windows. os.Rename cannot guarantee an atomic replace there (golang/go#22397), and the package does not build for it.
  • fs.FS interop. fs.FS is a read-only interface, and atomic writes are outside its scope.
  • Atomic symlink replacement. Use google/renameio for that.
  • Detecting a cross-mount temp directory. Temp files are always created in the target's own directory, on the same mount, which is the only correct place for an atomic rename.

Documentation

Credits

The incremental PendingFile API, a staged file that is either committed into place or cleaned up, follows google/renameio.

Contributing

See CONTRIBUTING.md.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude, GPT, and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package atomicfile provides crash-safe atomic file writes (temp, fsync, rename, directory fsync, all through an *os.Root), bounded reads, regular-file opens, writability probes and stale-temp sweeps, using only the standard library. A nil error from a write means the data reached its final path.

A write without WithMode creates the file like os.Create (0666 through the umask and any inherited ACL) and never chmods or verifies it. WithMode stages the payload in an owner-only file and proves the mode the filesystem stored on the staging and final file, failing with ErrModeNotStored instead. https://github.com/cplieger/atomicfile documents every guarantee.

Index

Examples

Constants

This section is empty.

Variables

View Source
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

func EnforceMode(f *os.File, want os.FileMode) (os.FileMode, error)

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/v4"
)

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

func IsPackageTemp(name string) bool

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

func OpenParentInRoot(root *os.Root, name string) (*os.Root, string, error)

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

func OpenRegular(path string) (*os.File, os.FileInfo, error)

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/v4"
)

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

func OpenRegularInRoot(root *os.Root, name string) (*os.File, os.FileInfo, error)

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/v4"
)

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

func OpenRegularInRootNoFollow(root *os.Root, name string) (*os.File, os.FileInfo, error)

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

func ReadBounded(ctx context.Context, path string, maxBytes int64) ([]byte, error)

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/v4"
)

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

func ReadBoundedFile(ctx context.Context, f *os.File, maxBytes int64) ([]byte, error)

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/v4"
)

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

func RemoveFileInRoot(root *os.Root, name string) error

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/v4"
)

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/v4"
)

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

func ValidatePath(path string) error

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

func WalkDirInRoot(ctx context.Context, root *os.Root, fn fs.WalkDirFunc) error

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/v4"
)

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

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

func (e *NotRegularError) Error() string

func (*NotRegularError) Unwrap

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

func WithLogger(l *slog.Logger) Option

WithLogger sets a custom logger. If not provided, slog.Default() is used.

func WithMaxBytes

func WithMaxBytes(n int64) Option

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

func WithMkdirMode(mode os.FileMode) Option

WithMkdirMode creates missing parent directories at mode before writing; without it a missing parent is an error. The mode is enforced on each created directory (a pre-existing one is never chmod'ed), or the write fails with ErrModeNotStored. It governs directories only; the file's mode is WithMode's. Sweeps and EnsurePrivateDir ignore it. Result.Durable is false if a created directory's parent fsync failed.

func WithMode

func WithMode(mode os.FileMode) Option

WithMode makes mode a guarantee: the staging file is created and proved owner-only before any data is written, and the final file is proved to hold mode, or the write fails matching ErrModeNotStored. Last call wins.

Without it the file is ordinary: created like os.Create (0666 through the umask and inherited ACLs) and never chmod'ed or checked. Pass it for any file whose readers must be restricted.

func WithRecursive

func WithRecursive(recursive bool) Option

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

func WithRepairOwnedDir(repair bool) Option

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

type PendingFile struct {
	*os.File
	// contains filtered or unexported fields
}

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/v4"
)

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

func NewPendingFile(ctx context.Context, path string, opts ...Option) (*PendingFile, error)

NewPendingFile creates a temp file destined to atomically replace path. Write to it, then call Commit to finalize or Cleanup to abort. File mode: see WithMode. ctx is checked before the temp is created.

Example
package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"

	"github.com/cplieger/atomicfile/v4"
)

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 is NewPendingFile for name, a path relative to root, with WriteFileInRoot's confinement; the lifecycle is identical. File mode: see WithMode. The caller owns root and must keep it open for the PendingFile's lifetime; a caller-provided root is never closed. 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/v4"
)

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 check, WithMode enforcement, fsync, close), renames the temp into place and fsyncs the parent directory. It is idempotent; after Cleanup it returns ErrAborted, and after it Cleanup is a no-op. ctx is checked through close (a cancelled context aborts and removes the temp), not between close and rename.

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/v4"
)

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/v4"
)

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

func ProbeWritable(ctx context.Context, dir string, opts ...Option) (ProbeResult, error)

ProbeWritable proves dir is writable by doing what an atomic write does (create a temp, write and flush a byte, close, unlink) and reports the first stage that failed in the ProbeResult; err != nil only means the probe could not start (empty dir, done ctx). The probe file is a TempName, so a leftover is reclaimed by CleanupStaleTemps. A missing dir fails at ProbeStageCreate unless WithMkdirMode creates it; dir may be relative. Under WithMode the probe must prove an owner-only staging file, as a write would. ctx is checked once; a probe that has begun always runs its own cleanup.

Example
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/cplieger/atomicfile/v4"
)

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 an escaping name is refused and reported at ProbeStageCreate (ProbeStageMkdir under WithMkdirMode). Everything else, the WithMode rule included, is ProbeWritable's. The caller owns root and keeps it open; a nil root returns ErrUnsafePath.

Example
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/cplieger/atomicfile/v4"
)

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) OK

func (r ProbeResult) OK() bool

OK reports whether every stage passed.

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

func WriteFile(ctx context.Context, path string, data []byte, opts ...Option) (Result, error)

WriteFile atomically writes data to path. File mode: see 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/v4"
)

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/v4"
)

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/v4"
)

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 is WriteFile for name, a path relative to root: every filesystem operation runs through the *os.Root, so a symlink or ".." component in name can never write outside root's tree. File mode: see 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/v4"
)

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

func WriteReader(ctx context.Context, path string, r io.Reader, opts ...Option) (Result, error)

WriteReader atomically writes the contents of r to path. File mode: see WithMode. An io.WriterTo r is used for efficient copying, so cancellation is coarse on that path (per chunk, or after a single-shot copy); ctx is still honored at the barrier, so a cancelled write leaves no partial target.

Example
package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"
	"strings"

	"github.com/cplieger/atomicfile/v4"
)

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/v4"
)

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. File mode: see 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/v4"
)

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/v4"
)

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 enforcing WithMode's mode on the temp
	// file; it occurs only under WithMode.
	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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL