atomicfile

package module
v3.1.0 Latest Latest
Warning

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

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

README

atomicfile

Go Reference Go version Test coverage Mutation OpenSSF Best Practices OpenSSF Scorecard

Crash-safe atomic file writes for Go

A standalone Go library providing atomic file writes (temp→fsync→rename→dir-fsync), path cleaning with os.Root-based containment, bounded reads, and streaming writes. Standard-library only, no external runtime dependencies.

Every write is os.Root-confined: the *InRoot APIs use the caller's root directly, and the absolute-path APIs open the target's parent directory as a root and write through it.

Platform Support

Linux only (including Docker/containers). Windows is unsupported by design: os.Rename cannot guarantee atomicity on Windows (golang/go#22397). macOS/BSD may work but is untested.

Install

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

Usage

package main

import (
	"context"
	"log"
	"os"
	"strings"

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

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

	// Atomic write with default mode (0644). The returned Result reports the
	// final path and whether the write is crash-durable.
	res, err := atomicfile.WriteFile(ctx, "/tmp/data.txt", []byte("hello"))
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("wrote %s (durable=%v)", res.Path, res.Durable)

	// Atomic write with custom mode.
	atomicfile.WriteFile(ctx, "/tmp/secret.txt", []byte("s3cr3t"),
		atomicfile.WithMode(0o600))

	// Streaming write from an io.Reader (mode via WithMode).
	atomicfile.WriteReader(ctx, "/tmp/stream.txt", strings.NewReader("streamed"),
		atomicfile.WithMode(0o644))

	// PendingFile for incremental writes (mirrors google/renameio).
	pf, _ := atomicfile.NewPendingFile(ctx, "/tmp/pending.txt")
	defer pf.Cleanup()
	pf.Write([]byte("incremental"))
	pf.Commit(ctx)

	// Auto-create parent directories.
	atomicfile.WriteFile(ctx, "/tmp/nested/dir/file.txt", []byte("deep"),
		atomicfile.WithMkdirMode(0o755))

	// Confined I/O through an *os.Root: name is relative to the root,
	// and a symlink or ".." in it can never escape the root's tree.
	root, _ := os.OpenRoot("/tmp")
	defer root.Close()
	atomicfile.WriteFileInRoot(ctx, root, "rooted.txt", []byte("confined"))

	// Read it back through the same root: open via the root (so the path stays
	// confined), then bound the read with ReadBoundedFile.
	rf, _ := root.Open("rooted.txt")
	defer rf.Close()
	rooted, _ := atomicfile.ReadBoundedFile(ctx, rf, 1<<20)
	log.Printf("read %d confined bytes", len(rooted))

	// Bounded read.
	data, _ := atomicfile.ReadBounded(ctx, "/tmp/data.txt", 1<<20)
	log.Printf("read %d bytes", len(data))
}

API

Write Functions

All write primitives return (Result, error); inspect Result.Durable for crash durability (see Result and Durability for the nil-error contract).

  • WriteFile(ctx, path, data, opts ...Option) (Result, error): atomic write (default mode 0644)
  • WriteReader(ctx, path, r, opts ...Option) (Result, error): atomic write from io.Reader (uses the io.WriterTo fast path when available; mode via WithMode)
  • WriteFileInRoot(ctx, root, name, data, opts ...Option) (Result, error): atomic write of data to name relative to an *os.Root; every filesystem op runs through the root, so a symlink or .. in name cannot escape its tree
  • WriteReaderInRoot(ctx, root, name, r, opts ...Option) (Result, error): same, streaming from an io.Reader
Streaming Writer
  • NewPendingFile(ctx, path, opts ...Option) (*PendingFile, error): open a temp file for incremental writing (mode via WithMode)
  • NewPendingFileInRoot(ctx, root, name, opts ...Option) (*PendingFile, error): same, confined to an *os.Root: the temp, rename, and parent-dir fsync all run through the caller's root, which stays caller-owned (keep it open through Commit/Cleanup)
  • (*PendingFile).Commit(ctx) (Result, error): chmod + fsync + close + rename + dir-fsync (finalize). Idempotent: repeated calls return the first result. Returns ErrAborted if called after Cleanup.
  • (*PendingFile).Cleanup() error: close + remove (abort; no-op after Commit, idempotent). Safe to defer immediately after NewPendingFile.

PendingFile embeds *os.File, so the full io.Writer/io.ReaderFrom/fmt.Fprintf surface is available, and Name() reports the staged temp's path for inspection before Commit publishes it. A WithMaxBytes cap is enforced as you write (BytesWritten() reports the count, Truncate re-syncs it, and a call that would cross the cap is rejected whole) and re-verified against the staged file's actual size at Commit, so bytes staged outside the tracked stream (WriteAt, Write after Seek, a reopen of the temp by path) cannot publish an over-cap file either.

Read Functions
  • ReadBounded(ctx, path, maxBytes) ([]byte, error): size-checked read; returns ErrFileTooLarge past the limit
  • ReadBoundedFile(ctx, f, maxBytes) ([]byte, error): size-checked read from an already-open *os.File (the seam for reading a file opened through an *os.Root); the caller owns and closes f
  • ReadBoundedInRoot(ctx, root, name, maxBytes) ([]byte, error): the confined read, and the read-side counterpart to WriteFileInRoot: a symlink or .. component in name cannot redirect the read out of the root's tree. Only a regular file is read, and the open is non-blocking, so a FIFO planted in the tree is refused with ErrNotRegular instead of stalling the caller. The caller owns root.
  • OpenRegularInRoot(root, name) (*os.File, os.FileInfo, error): the open half of ReadBoundedInRoot, which is now literally this plus ReadBoundedFile. Opens name through the root read-only and non-blocking, stats the OPEN HANDLE rather than the pathname, and refuses a directory, FIFO, device node or socket with ErrNotRegular. The caller owns and closes the descriptor.
  • OpenRegular(path) (*os.File, os.FileInfo, error): the ambient-path sibling, for a full path into a directory the caller trusts. O_NOFOLLOW makes the kernel refuse a symlink under the name (ErrSymlinkTarget), which no check-then-open sequence can do without a race; the path itself goes through the ValidatePath rule. This does not change ReadBounded, which still follows symlinks by design.

Both openers exist because the descriptor is what a consumer cannot rebuild from bytes: a caller streaming the file through a decoder or decryptor never materializes it, and a caller caching the file needs the FileInfo the bytes came from to record a FileIdentity. Neither opener pins the ancestor components; OpenParentInRoot does that.

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 the operation lands somewhere inside the tree the caller never inspected. These two close that gap for callers working in a tree others can write to: a co-mounted Docker volume, a shared NFS export.

  • WalkDirInRoot(ctx, root, fn fs.WalkDirFunc) error: stream a confined tree. Entries arrive in fixed batches rather than as one materialized inventory per directory, so a large or hostile directory is never resident before the callback can refuse it; a named pipe planted where a directory was is refused instead of blocking the walk; a symlinked directory is never descended. The callback is an fs.WalkDirFunc, called exactly as fs.WalkDir calls one: the root first as ".", then each entry pre-order, a directory that cannot be opened or finished reported through the callback for its own path, fs.SkipDir/fs.SkipAll honoured. Two deliberate differences: entries arrive in directory order, sorted within a batch only, and a directory's own entries are all visited before the walk descends into its subdirectories. The walk stops between batches once ctx is done; a caller wanting per-entry cancellation checks ctx in the callback. Walk a subtree by passing root.OpenRoot(sub).

  • OpenParentInRoot(root, name) (parent *os.Root, base string, err error): open name's parent directory as its own root, pinned. Every component is Lstat-ed (a symlink is refused, not followed), required to be a real directory, opened as a root, and confirmed with os.SameFile against the directory that was inspected, so a component replaced mid-open is refused too. Naming only base through parent afterwards removes every ancestor from the operation's path. The returned root is always a fresh handle the caller closes (including for a flat name, where it is a second handle on the root's own directory), so the close is unconditional and never closes the caller's root. A vanished component matches fs.ErrNotExist (the benign racing-deletion case), a refused one does not.

  • RemoveFileInRoot(root, name) error: that descent applied to an unlink. Only a regular file is removed; a directory, symlink, device node, socket or FIFO wearing the name is refused with ErrNotRegular and left as found. A missing file is reported (fs.ErrNotExist) rather than swallowed; whether an already-gone name is success is the caller's judgement.

  • CleanupStaleTempsInRoot(ctx, root, maxAge, opts ...Option) (SweepResult, error): the confined sweep. It uses both of the above: enumerating through WalkDirInRoot (so a large or hostile directory is not materialized before the sweep sees its first entry) and unlinking every candidate through a pinned parent, so an ancestor swapped for a symlink cannot redirect a removal at another file inside the tree. Same signature shape, outcome model and maxAge rule as CleanupStaleTemps; the one difference is that confinement.

Private Directories and Enforced Modes
  • EnforceMode(f *os.File, want os.FileMode) (os.FileMode, error): fchmod the open handle to want, then fstat the same handle and return the mode the filesystem actually stored; a mismatch is ErrModeNotStored, naming both modes. Works for a file or a directory, since both are an *os.File.
  • EnsurePrivateDir(dir string, opts ...Option) (PrivateDir, error): establish custody of one directory level only the effective uid may enter: mkdir 0700, open O_DIRECTORY|O_NOFOLLOW, fstat the handle, require the owner uid, repair the mode if we created it, refuse it if we did not.
type PrivateDir struct {
	Mode     os.FileMode // the mode the filesystem stored, read back from the handle
	Created  bool        // this call created the directory
	Repaired bool        // the created directory's mode had to be corrected
}

A mode argument to mkdir(2) or open(2) is a request, not a result. umask narrows it, and a filesystem carrying an inheritable ACL can widen the outcome regardless of what was asked: measured on a ZFS nfs4acl dataset, an inheritable group@:rwx ACE stores 0770 for a 0o700 mkdir, and a child of an already-0700 parent comes back 0770 too, so a narrower parent does not cover it. EnforceMode is the chmod and the re-stat, on one descriptor, so the mode it returns is the mode the filesystem holds.

EnsurePrivateDir composes that into the sequence a process needs when its private directory lives inside a parent other users can write (a state directory under /tmp, an admin-socket directory):

  • mkdir 0700, remembering whether this call created the level. Every decision below turns on that distinction, which os.MkdirAll cannot report.
  • Open O_DIRECTORY|O_NOFOLLOW|O_RDONLY. The kernel refuses a planted symlink instead of following it (ErrSymlinkTarget), refuses anything that is not a directory (ErrNotDirectory), and cannot be stalled indefinitely by a planted FIFO.
  • fstat the handle, then require os.Geteuid() to own it (ErrNotOwned). Ownership, not just mode: a perfectly-moded 0700 directory owned by another uid passes every other check and its owner can still replace it (with a symlink the caller then follows) after the verdict returns.
  • If this call created it, EnforceMode to 0700. That is the ACL repair, and it is safe precisely because we made the directory: no other writer has ever held that name. A pre-existing directory is refused instead, unless the caller passes WithRepairOwnedDir(true), which repairs it because the euid-ownership check has already proved the directory is the caller's own (see the option table). That option exists so a mode fix does not become an outage the first time an app meets a directory an earlier release of itself created.
  • If it pre-existed, it is never chmod'ed and is refused when any group or other bit is set (ErrModeTooOpen). Repairing a directory another principal made would take over their name and hand them whatever gets written under it.

One level per call, deliberately. dir's parent is not created, inspected, or vouched for; a multi-level path is a loop over the levels, outermost first, 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 the caller's later use: the handle is closed before the call returns, so a subsequent ReadDir, Remove, Open or Mkdir through the pathname re-resolves every component and re-opens the window the check closed. To close that gap, hold the directory open for its whole lifetime and act through an *os.Root, naming only the leaves inside it.

Of the functional options, WithRepairOwnedDir(true) opts into repairing a too-open directory this same identity already owns, and WithLogger supplies the logger for the one Warn a mode repair emits (a filesystem that ignores mode requests is news for every other mkdir in the program too). The mode is not a parameter: a "private directory" with a caller-chosen mode is a different primitive.

Utilities
  • CleanupStaleTemps(ctx, dir, maxAge, opts ...Option) (SweepResult, error): remove orphaned temp files left by interrupted writes, reporting Removed / Failed / Unreadable. Only files matching the package's exact temp shape (.atomicfile-<digits>.tmp) and older than maxAge are reclaimed; caller-owned files that merely share the prefix or suffix (.atomicfile-notes.tmp, config.tmp-backup) are never touched. Each candidate is re-checked immediately before removal, so a same-named fresh temp created during the scan is spared. The sweep stops once ctx is done. Same signature shape and outcome model as CleanupStaleTempsInRoot; the one difference is confinement. See Orphaned temps for what leaves one behind and how to pick maxAge.
  • Identify(info os.FileInfo) FileIdentity + Matches / Changed / Recorded / ModTime: reload-staleness comparison for a reader caching a file another process publishes. See Reload staleness.
  • TempName() string and IsPackageTemp(name string) bool: the temp-name convention as a contract. TempName returns a fresh name of the exact shape the sweeps reclaim; IsPackageTemp reports whether a directory entry's name is one. Use them instead of rebuilding .atomicfile-<digits>.tmp by hand. os.CreateTemp(dir, ".atomicfile-*.tmp") only matches because Go happens to substitute decimal digits for *, which its documentation does not promise.
  • ValidatePath(path string) error: the path gate the absolute-path functions apply (WriteFile, WriteReader, NewPendingFile, ReadBounded), for a caller that has to accept or refuse a path before it writes: a config value read at startup, a CLI flag, a request field. nil means acceptable; otherwise it returns the same error the write would: ErrEmptyPath, or ErrUnsafePath for an embedded NUL or a path that is not absolute once cleaned. It delegates to the one private validator the writes use, so an acceptance here and a rejection at write time cannot disagree. filepath.IsAbs is the usual stand-in and is a different rule: it accepts "/tmp/a\x00b", which every write here refuses. Nothing on the filesystem is consulted (the path need not exist and its parent need not be a directory), so nil says the path is well formed, not that a write there will succeed (ProbeWritable answers that, by writing). Being absolute is not containment: filepath.Clean normalizes .., so use the *os.Root-backed APIs to confine writes to a tree.
Writability Probe
  • ProbeWritable(ctx, dir, opts ...Option) (ProbeResult, error): prove a directory is genuinely writable by doing what a write does (create a temp file, write and flush a byte, close it, unlink it), and report which stage failed. dir may be relative; WithMkdirMode creates it first.
  • ProbeWritableInRoot(ctx, root, name, opts ...Option) (ProbeResult, error): the same probe confined to an *os.Root (name is relative to it, "." for the root itself), for a caller that already holds a root over the directory it is about to write to. An escaping name is refused by the root.
type ProbeResult struct {
	Err    error      // the failure from Stage, unwrapped to the filesystem error
	Dir    string     // directory probed
	Name   string     // probe file's base name; always satisfies IsPackageTemp
	Stage  ProbeStage // first stage that failed, or ProbeStageNone
	Leaked bool       // probe file still on disk
}

A stat of the mode bits is not an answer: an NFS or FUSE mount, a read-only bind mount, and a Docker volume owned by another UID all present a writable-looking directory that refuses the first write. The stages are the whole ladder (ProbeStageMkdir, Create, Write, Sync, Close, Remove), because a filesystem can fail at any one of them.

Policy stays with the caller. A stage failure is reported in the ProbeResult, never as the error return: err != nil means only that the probe could not be attempted (empty dir, cancelled context). res.OK() is the everything-passed answer; res.Writable() is the split for a caller that wants to warn about a failed cleanup and keep running, since a failure at ProbeStageClose or later still proves the directory took the bytes.

The probe file is named with TempName(), so a probe orphaned by a crash (or left behind by a directory that denies the unlink) is reclaimed by CleanupStaleTemps like any other temp, by construction rather than by a naming convention each caller reproduces.

ctx is checked once, before anything is created; the stages are single filesystem calls the OS does not make interruptible, and a probe that has begun always runs its own cleanup, so guard a possibly-wedged mount with your own timeout around the call.

Reload staleness

A process that caches a file written by someone else needs to know, from a stat alone, whether its in-memory copy is still current. The test for a file published by rename is mtime equality AND os.SameFile identity, and it is knowledge about this package's write barrier, which is why the primitive lives here:

// after loading
id := atomicfile.Identify(info)

// on every poll
info, err := os.Stat(path)
if err != nil { /* caller's policy */ }
if id.Changed(info) {
	// reload, then re-Identify
}

Both legs are load-bearing, because two different write mechanisms change a file's content and each defeats one half of the naive check:

  • An in-place writer (os.WriteFile, an editor, truncate-and-write) keeps the same inode and usually moves the mtime forward — usually, because inode times come from a coarse clock tick, so two writes inside one tick carry byte-identical mtimes. An identity-only check calls that unchanged.
  • A publish-by-rename writer (every write in this package) installs a different inode. Normally its mtime differs too, but it need not: a backup restore, rsync -t, tar -xp, or any re-publication of an archived generation lands new content carrying the old timestamp. An mtime-only check calls that unchanged, and the stale copy is then served until something else happens to touch the file.

Size is a third leg, not a redundant one, and Matches does not compare it. Each leg covers a different replacement, and neither two-leg form dominates the other:

second write mtime size inode mtime && size Matches (mtime && SameFile)
rename, same tick, equal length same same new misses catches
rename, same tick, length changed same differs new catches catches
in-place, same tick, equal length same same same misses misses
in-place, same tick, length changed same differs same catches misses
anything crossing a tick differs — — catches catches

So mtime && SameFile && size strictly dominates either pair. A reader of a file only this package publishes needs Changed alone; a reader whose file may also be rewritten in place keeps its own info.Size() != cached beside it — one != at the call site, which is why no size leg is exported here. Row 3 is unreachable for any stat-based check, and that limit is unchanged either way.

The zero FileIdentity records nothing and reports Changed, which is the fail direction a cache wants: a spurious reload costs one read, a missed reload serves stale data indefinitely. FileIdentity is a comparison primitive, not a policy: degradation states, stat-error handling, and re-stat cadence stay with the caller.

Orphaned temps

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 leaves a temp behind, and so does a PendingFile abandoned without Commit or Cleanup. Atomicity is unaffected (nothing was published and the previous file at the target is untouched), so an orphan costs disk, not correctness.

Nothing in this library reclaims them on its own. There is no background sweeper, no finalizer, and no cleanup on the next write. Reclamation is CleanupStaleTemps / CleanupStaleTempsInRoot, called by the consumer where it knows a sweep is safe: at startup, or on a schedule.

Picking maxAge. It must exceed the longest time any concurrent writer may hold a temp: a sweep cannot tell an orphan from a write in progress, because 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 staged, then held across slow work, then committed: measured, with the temp backdated past a one-hour maxAge the sweep unlinked it and the following Commit failed with *WriteError{PhaseRename} wrapping ENOENT. Nothing was lost from the target; that write was. A non-positive maxAge skips the sweep with a Warn instead of reaping everything, so a zero from an unset config cannot empty a directory.

Result and Durability

type Result struct {
	Path    string // cleaned final path (absolute for the package-level writers; root-relative for WriteFileInRoot/WriteReaderInRoot)
	Durable bool   // true only when the file and every directory its path depends on were fsynced
}

Every atomic write follows the sequence: create temp file → write data → fsync temp → close → rename to final path → fsync parent directory. After a crash the file contains either the complete old content or the complete new content, never a partial write. The directory fsync makes the rename durable even if the system loses power immediately after the call returns.

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 (for example an EIO from a failing disk; the rename has already completed, and the write logs the fsync failure at Warn). Result.Durable distinguishes those two outcomes, 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.

Callers that require strict durability treat Durable == false as actionable (retry or alert); callers that only need atomicity can ignore it.

WithMkdirMode is covered by the same guarantee. Each directory the write creates has its own parent fsynced as it is made, because a directory entry that was never fsynced into its parent can vanish in a crash and take the whole subtree with it, including a file that was itself fsynced and renamed. A three-level WithMkdirMode write therefore fsyncs four directories, and Result.Durable is false if any of them failed.

Functional Options

All write functions accept variadic Option values. Omit options for defaults.

Option Description
WithLogger(l) Custom *slog.Logger for diagnostic output (default: slog.Default())
WithMode(mode) File permission (default: 0o644)
WithMkdirMode(mode) Create the parent directory (and missing ancestors) with this mode before writing. Without it, a missing parent is an error. The mode is enforced on each directory created (a request through mkdir(2) is narrowed by umask and can be widened by an ACL) and each one's parent is fsynced.
WithRepairOwnedDir(repair) EnsurePrivateDir only: true repairs a pre-existing directory whose owner is already the effective uid, instead of refusing it; false keeps the default refusal. For adopting your own past output; ignored by writes.
WithRecursive(recursive) Stale-temp sweeps only: true makes CleanupStaleTemps / CleanupStaleTempsInRoot descend into subdirectories; false keeps the default one-directory sweep. Ignored by writes.
WithMaxBytes(n) Cap staged content at n bytes, the write-side mirror of ReadBounded. Over-cap writes match ErrFileTooLarge and leave the previous target intact. n <= 0 = no cap.

Errors

Sentinel Meaning
ErrEmptyPath The path argument was empty
ErrUnsafePath The path is not absolute, contains a null byte, or names no entry (., ..)
ErrFileTooLarge The file exceeded the ReadBounded size limit, or content exceeded a WithMaxBytes write cap
ErrSymlinkTarget The target of a write is a symlink (always refused); or OpenRegular refused one
ErrNotRegular Name resolved to a non-regular file (dir, FIFO, device, socket); the mode is named. Refused on read, unlink and write
ErrNotDirectory EnsurePrivateDir: the name is occupied by a file, FIFO, device node or socket
ErrNotOwned EnsurePrivateDir: the directory's owner is not the effective uid (or could not be determined)
ErrModeTooOpen EnsurePrivateDir: a pre-existing dir grants group/other access, no repair opted in
ErrModeNotStored EnforceMode: the mode read back after the chmod is not the mode that was asked for
ErrAborted PendingFile.Commit was called after Cleanup aborted the pending write

The package-level path check is not a containment boundary. filepath.Clean normalizes any .. in an absolute path rather than rejecting it (for an absolute path there is nothing to escape), so ErrUnsafePath only guards against a non-absolute or null-byte path. Callers that need to confine writes to a directory tree use the *os.Root-backed write APIs (WriteFileInRoot / WriteReaderInRoot). Callers that need to confine reads should open the file through an *os.Root and pass that already-confined handle to ReadBoundedFile, which then applies the same size and context bounds.

Failures in the write barrier (open destination / create temp, write, chmod, sync, close, rename) are reported as *WriteError{Err, Phase}, where Phase is one of PhaseTempCreate, PhaseTempWrite, PhaseTempChmod, PhaseTempSync, PhaseTempClose, or PhaseRename. PhaseTempCreate covers opening the destination for writing (a missing parent without WithMkdirMode surfaces here) as well as creating the temp file inside it. Pre-barrier failures keep their own error types: path-validation and symlink failures use the sentinels above, context failures wrap the standard-library context error (context.Canceled / context.DeadlineExceeded), and a WithMkdirMode parent-directory creation failure wraps the underlying os error behind the atomicfile: prefix. All are inspectable with errors.Is / errors.As, and a *WriteError always means the data did not reach its final path.

All write functions refuse to write to a path that is currently a symlink, returning ErrSymlinkTarget, unconditionally; there is no opt-out. os.Rename replaces the symlink itself rather than the file it points to, which is rarely the caller's intent and can lead to data loss or security issues. Writing through a symlink is not supported; if the link's target is a path you already trust, resolve it with filepath.EvalSymlinks and write to the resolved path.

They also refuse a target already occupied by anything else that is not a regular file, returning ErrNotRegular: the same verdict ReadBoundedInRoot gives what it will read and RemoveFileInRoot gives what it will unlink. rename(2) overwrites any non-directory, so without the refusal a write could replace a FIFO, a socket or a device node this package never created. An existing regular file is still overwritten, which is the point of the package. The check reads the target before it renames, because rename(2) has no "only if the destination is a regular file" mode, so its value is refusing the states that are there to be found, not winning a race.

Reads behave differently: ReadBounded follows symlinks by design (os.Open resolves them), so it does NOT refuse a symlink at path. When reading from a directory writable by a less-trusted principal, confine the path yourself: open the file through an *os.Root and read it with ReadBoundedFile, which applies the same size and context bounds without following symlinks out of the root. OpenRegularInRoot is that open, already written; OpenRegular is the ambient-path form for a caller holding a full path into a directory it trusts, and it is the one read entry point that does refuse a symlink under the name: O_NOFOLLOW has the kernel refuse the open, which a check-then-open sequence cannot do without a race.

An *os.Root does not pin a multi-component name: OpenParentInRoot and RemoveFileInRoot do, see Confined Traversal and Removal.

Unsupported by Design

Feature Rationale
Windows rename-over semantics Target platform is Linux. os.Rename is atomic on Linux. Windows cannot guarantee atomicity (golang/go#22397). google/renameio also refuses Windows.
fs.FS interop fs.FS is a read-only interface. Atomic writes are inherently outside its scope.
Atomic symlink replacement Out of scope. Use google/renameio if needed.
Umask-aware permissions The library uses Chmod for exact permissions (ignoring umask). This is the correct secure default for server/CLI tools. Equivalent to renameio's WithStaticPermissions.
TempDir cross-mount detection Temp files are always created in the target directory (same mount point), the only correct approach for atomic rename.

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md for the conventions and how to run the checks locally.

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

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/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

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/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

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/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

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/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

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/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

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/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

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/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

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 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 WithMode

func WithMode(mode os.FileMode) Option

WithMode sets the permission applied to the written file. Defaults to 0o644.

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/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

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. 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

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

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

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

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

Jump to

Keyboard shortcuts

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