atomicfile

package module
v2.4.0 Latest Latest
Warning

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

Go to latest
Published: Jul 26, 2026 License: GPL-2.0, GPL-3.0 Imports: 15 Imported by: 5

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/v2@latest

Usage

package main

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

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

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)

	// Preserve existing file permissions across replace.
	atomicfile.WriteFile(ctx, "/tmp/data.txt", []byte("updated"),
		atomicfile.WithPreserveMode())

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

	// Skip fsync for speed (atomicity without durability).
	atomicfile.WriteFile(ctx, "/tmp/cache.txt", []byte("fast"),
		atomicfile.WithNoSync())

	// Confined I/O through an *os.Root (Go 1.24+): 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
Utilities
  • CleanupStaleTemps(dir, maxAge, opts ...Option) (removed int, err error): remove orphaned temp files left by interrupted writes, returning how many were removed. 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.
  • Identify(info os.FileInfo) FileIdentity + Matches / Changed / Recorded / ModTime: reload-staleness comparison for a reader caching a file another process publishes. See Reload staleness.

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 correct test 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 moves the mtime forward. 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 deliberately not part of the comparison: a same-size replacement is exactly the case a size check misses, and a differing size is already caught by one of the two legs.

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.

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 file + parent-dir fsync both completed
}

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 the parent-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 or use WithNoSync() to skip the directory fsync entirely.

Note on auto-created directories. When WithMkdirMode creates new parent directories, only the file's immediate parent is fsynced. The newly created intermediate directories are not fsynced into their own parents, so the durability guarantee above applies only when the full parent path already exists. If you need durability into a freshly created directory tree, create and fsync the directories before writing.

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.
WithPreserveMode() Stat the target and reuse its mode (like renameio.WithExistingPermissions), falling back to WithMode if it does not exist or cannot be stat-ed
WithPreserveOwnership() Stat the target and chown the temp to match its uid/gid (requires CAP_CHOWN; no-op when the target is absent, cannot be stat-ed, or off Unix)
WithNoSync() Skip fsync for speed (atomicity without durability). Result.Durable is then always false.
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.
WithAllowSymlinkTarget() Permit writing to a symlink path (default: refuse with ErrSymlinkTarget)

Errors

Sentinel Meaning
ErrEmptyPath The path argument was empty
ErrUnsafePath The path is not absolute or contains a null byte
ErrFileTooLarge The file exceeded the ReadBounded size limit, or content exceeded a WithMaxBytes write cap
ErrSymlinkTarget The target is a symlink and WithAllowSymlinkTarget was not set
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.

By default, all write functions refuse to write to a path that is currently a symlink, returning ErrSymlinkTarget. 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.

To opt in to writing through a symlink (replacing the symlink with a regular file), use WithAllowSymlinkTarget(). To write to the link's target instead, resolve it with filepath.EvalSymlinks first.

Metadata reads under WithAllowSymlinkTarget. The symlink-following stat that WithPreserveMode / WithPreserveOwnership perform runs through an os.Root of the target's parent directory. A symlink target whose destination is absolute or escapes that directory is not followed for the metadata read: preserve-mode falls back to the WithMode value and preserve-ownership becomes a no-op for such links (the write itself still replaces the link). Links resolving within the parent directory are followed as normal.

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 (Go 1.24+) and read it with ReadBoundedFile, which applies the same size and context bounds without following symlinks out of the root.

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

GPL-3.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 the parent-directory fsync failed. Result.Durable distinguishes those two outcomes: it is true only when both the file and its parent directory were fsynced, 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.

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.

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: mtime equality AND os.SameFile identity, because an in-place writer keeps the inode while 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; a size comparison misses exactly the same-size replacement. 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.

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 when content exceeds a WithMaxBytes
	// write cap (there it arrives 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 and
	// WithAllowSymlinkTarget was not set.
	ErrSymlinkTarget = errors.New("atomicfile: target is a symlink")
	// ErrNotRegular is returned by ReadBoundedInRoot when the name resolves to
	// something other than a regular file — a directory, named pipe, device node or
	// socket. It is a distinct sentinel because a caller that maps failures onto
	// protocol responses (an HTTP handler answering 400 for a directory but 404 for a
	// missing file) has to tell this case apart from the others; the error text names
	// the actual mode for diagnosis. Match with errors.Is.
	ErrNotRegular = errors.New("atomicfile: not a regular file")
	// ErrAborted is returned by PendingFile.Commit when the pending file was
	// already aborted by a prior Cleanup. The temp file was removed and nothing
	// reached the final path, so Commit reports this rather than a zero-value
	// Result with a nil error, which would falsely signal success.
	ErrAborted = errors.New("atomicfile: pending file aborted")
)

Sentinel errors.

Functions

func CleanupStaleTemps

func CleanupStaleTemps(dir string, maxAge time.Duration, opts ...Option) (removed int, err error)

CleanupStaleTemps removes temp files in dir that this package created (".atomicfile-<digits>.tmp") and whose mtime is older than maxAge. It returns the number removed. A missing dir is not an error. Best-effort per file: individual stat/remove failures are logged at Debug and skipped (see reapStaleTemp); only a readdir failure is returned.

Example
package main

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

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

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)

	removed, _ := atomicfile.CleanupStaleTemps(dir, time.Hour)
	fmt.Println(removed)
}
Output:
1

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, so a symlink at path is resolved and its target is read. Callers reading from a directory writable by a less-trusted principal should confine the path themselves: open the file through an *os.Root and read it with ReadBoundedFile, which applies the same size and context bounds.

Example
package main

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

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

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 added in v2.1.0

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

ReadBoundedFile reads up to maxBytes from an already-open file using the same size validation as ReadBounded: it returns ErrFileTooLarge if the file exceeds maxBytes (including if it grows past the limit during the read), and checks ctx before the size stat and before the read. The caller owns f; ReadBoundedFile does not close it.

This is the seam for callers that must open the file themselves before reading it — most importantly, opening through an *os.Root (Go 1.24+) to confine the path to a trusted directory, which ReadBounded cannot do because os.Open follows symlinks. Open the file via the root, then read it here to get the identical bounds and context handling.

func ReadBoundedInRoot added in v2.4.0

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 the read outside it (Go 1.24+ *os.Root).

It is the read-side counterpart to WriteFileInRoot. Without it, a caller that writes through a confined root has to hand-roll the read half — open through the root, require a regular file, avoid blocking on a FIFO, then delegate to ReadBoundedFile — which is exactly the sequence this package already owns on the write side. Every consumer that hand-rolls it re-derives the same three non-obvious details, and one of them getting it wrong is a confinement bypass.

Only regular files are read. A named pipe, device node or socket planted in the tree is rejected rather than opened, and the open is non-blocking so it cannot stall a caller even momentarily: open(2) on a FIFO with no writer blocks indefinitely, which for a single-goroutine scanner means a permanent hang.

The caller owns root; ReadBoundedInRoot does not close it.

Example
package main

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

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

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

Types

type FileIdentity added in v2.4.0

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.

The correct form of that test is knowledge about this package's own write barrier, which is why it lives here. Two different write mechanisms can change a file's content, and each defeats one half of the naive check:

  • An IN-PLACE writer (a plain os.WriteFile, an editor, a truncate-and-write) keeps the same inode and moves the mtime forward. Comparing identity alone would call 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, an rsync with -t, a tar extract with -p, or any re-publication of an archived generation lands new content carrying the OLD timestamp. Comparing mtime alone would call that unchanged, and the stale copy would then be served until something else happened to touch the file.

So the test is mtime equality AND os.SameFile identity, and both legs are load-bearing. Size is not part of it: a same-size replacement is exactly the case a size comparison misses, and a differing size is already covered by one of the two legs.

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 retains the os.FileInfo it was given. It is a comparison primitive, not a policy: what to do about a changed file, whether a stat error is fatal, and when to re-stat at all stay with the caller.

func Identify added in v2.4.0

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 added in v2.4.0

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 added in v2.4.0

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 added in v2.4.0

func (id FileIdentity) ModTime() time.Time

ModTime returns the captured modification time, or the zero Time when nothing was recorded. It is exposed for diagnostics — a log line or an assertion naming which generation is held — not for the freshness test, which Matches owns because the mtime alone is not sufficient.

func (FileIdentity) Recorded added in v2.4.0

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 Option

type Option func(*cfg)

Option configures an atomic write operation.

func WithAllowSymlinkTarget

func WithAllowSymlinkTarget() Option

WithAllowSymlinkTarget permits writing to a path that is currently a symlink. By default symlink targets are refused with ErrSymlinkTarget. Note the atomic rename REPLACES the symlink with a regular file; it does not write through to the link's target. Resolve with filepath.EvalSymlinks first if that is the intent.

func WithLogger

func WithLogger(l *slog.Logger) Option

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

func WithMaxBytes added in v2.3.0

func WithMaxBytes(n int64) Option

WithMaxBytes caps the content size an atomic write will stage, the write-side mirror of ReadBounded's bound: a writer that also owns the reader can refuse to persist a file its own read path would refuse to load, instead of silently writing something that fails open on the next read. WriteFile and WriteFileInRoot reject over-cap content before the temp file is created; WriteReader and WriteReaderInRoot reject the copy chunk that would cross the cap; a PendingFile rejects the Write/WriteString/ReadFrom call that would cross it, whole, so the staged temp never holds an over-cap prefix (see PendingFile.Write). The barrier additionally verifies the staged file's actual size before publication, so bytes staged outside those interfaces (WriteAt, Write after Seek, a reopen of the temp by path) 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 directory is an error.

func WithMode

func WithMode(mode os.FileMode) Option

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

func WithNoSync

func WithNoSync() Option

WithNoSync skips the fsync on both the temp file and the parent directory, providing atomicity without durability. Result.Durable is then always false.

func WithPreserveMode

func WithPreserveMode() Option

WithPreserveMode stats the target before writing and applies its existing mode to the new file, falling back to the WithMode value if the target does not exist or cannot be stat-ed (a non-ErrNotExist stat failure is logged at Warn).

func WithPreserveOwnership

func WithPreserveOwnership() Option

WithPreserveOwnership stats the target before writing and chowns the temp file to match the target's uid/gid. Requires CAP_CHOWN or root; a no-op when the target does not exist, cannot be stat-ed, or off Unix (a non-ErrNotExist stat failure is logged at Warn). Best-effort: the chown runs after the temp-file fsync, so unlike content and mode it is not crash-covered. A chown failure is logged at Warn and does not fail the write (the file lands with the writer's ownership).

func WithRecursive added in v2.4.0

func WithRecursive() Option

WithRecursive makes a stale-temp sweep descend into subdirectories. It affects CleanupStaleTemps and CleanupStaleTempsInRoot and is ignored by every write entry point.

Off by default, and the default is the interesting half: a sweep is a DESTRUCTIVE operation, so how much of the filesystem it touches must be stated at the call site rather than inferred from which function was reached for. Both sweeps therefore behave identically without it — one directory, no descent — and depth is opt-in.

Reach for it when temps can be staged below the directory you name. That happens whenever the caller's own output tree is nested, because a temp is always created in the SAME directory as its final target: a write to out/example.com/cert.pfx leaves its orphan in out/example.com, which a flat sweep of out/ never sees. A caller with a flat cache directory does not need it and should not pass it.

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 (root.Name() joined with the temp name — absolute for NewPendingFile), so the staged file can be handed to external verifiers before Commit. The configuration is captured at construction and reused at Commit, so durability options cannot drift between the two calls.

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 and refuses to publish an over-cap file (the error matches ErrFileTooLarge).

Every filesystem operation (temp creation, rename, parent-dir fsync, removal) 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); an abandoned PendingFile therefore holds two file descriptors (temp + root) until then, just as it holds its temp file on disk.

A PendingFile is not safe for concurrent use: Commit and Cleanup mutate unsynchronized lifecycle state (state, result, err). Confine each PendingFile to a single goroutine. The package-level WriteFile, WriteReader, ReadBounded, and CleanupStaleTemps are stateless and safe to call concurrently on distinct paths.

Example
package main

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

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

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

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 added in v2.2.0

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: every filesystem operation (temp creation, rename, parent-dir fsync, removal) runs through the *os.Root, so a symlink or ".." component in name can never touch anything outside root's tree. Write to the returned PendingFile, then call Commit to finalize or Cleanup to abort; the lifecycle (idempotent Commit, ErrAborted after Cleanup, retryable failed Cleanup) is identical to NewPendingFile. Mode defaults to 0o644 (override with WithMode). ctx is checked before the temp is created. A nil root returns ErrUnsafePath.

The caller owns root and must keep it open for the PendingFile's lifetime (through Commit or Cleanup); 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/v2"
)

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 added in v2.3.0

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 (WriteAt, Write after Seek) 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 — a successful Commit already moved the data into place, and a failed Commit already removed the temp. 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 — a failed Cleanup never falsely reports the temp gone, and a subsequent Commit still returns ErrAborted. Repeated Cleanup calls are therefore a no-op after success but a retry after a removal failure. 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, optional fsync, close), applies ownership, atomically renames the temp into place, and fsyncs the parent directory. With a WithMaxBytes cap set, the staged file's actual size is measured (fstat) and an over-cap file fails Commit with an error matching ErrFileTooLarge — bytes staged outside the append-stream model cannot publish. Commit is idempotent: repeated calls return the first result. Calling Commit after Cleanup returns ErrAborted — the temp was already removed, so there is nothing to commit, and a nil error would falsely signal that the data reached its final path. After a successful Commit, Cleanup is a no-op. ctx is checked through the temp-side barrier (before chmod, around the fsync, and before close); a context cancelled at or before close aborts and removes the temp. Once the barrier passes, ownership and the rename run without a further ctx check, so a context cancelled in the narrow window between close and rename still commits.

func (*PendingFile) ReadFrom added in v2.3.0

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, so the cap and accounting hold; uncapped it delegates to the embedded *os.File's ReadFrom (keeping the OS copy fast path) and records the copied size.

func (*PendingFile) Truncate added in v2.3.0

func (p *PendingFile) Truncate(size int64) error

Truncate resizes the staged temp and re-syncs the byte accounting to the new size, keeping the append-stream model coherent for callers that trim a trailing byte after encoding (e.g. dropping json.Encoder's newline before Commit). Growing the file beyond a WithMaxBytes cap is rejected with an error matching ErrFileTooLarge.

func (*PendingFile) Write added in v2.3.0

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 - no byte of it reaches the temp - with an error matching ErrFileTooLarge, so the staged content never holds an over-cap prefix and a later Commit cannot publish an over-cap file. Accepted bytes advance BytesWritten.

func (*PendingFile) WriteString added in v2.3.0

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), so io.WriteString and friends stay inside the stream model.

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 (which require an
	// absolute path); for the *InRoot functions it is root.Name() joined
	// with the cleaned relative name, so it is relative when the *os.Root
	// was opened with a relative path.
	Path string
	// Durable reports whether the write is guaranteed to survive a crash:
	// true only when the file and its parent directory were both fsynced.
	// It is false when WithNoSync was set, or when the parent-directory fsync
	// failed after the rename — in that case the data is present at Path but
	// may not survive an immediate power loss, and the fsync 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/v2"
)

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

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

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-------
Example (WithNoSync)
package main

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

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

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "cache.txt")
	res, _ := atomicfile.WriteFile(context.Background(), path, []byte("fast"),
		atomicfile.WithNoSync())
	// WithNoSync trades durability for speed, so the result is not durable.
	fmt.Println(res.Durable)
}
Output:
false

func WriteFileInRoot added in v2.1.0

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. It is the write-side analogue of opening a file through an *os.Root and reading it with ReadBoundedFile. 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/v2"
)

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"))
	// Read it back through the same root with the bounded-read seam.
	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; that fast path bypasses the per-Read context check, so cancellation is coarse (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/v2"
)

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

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 added in v2.1.0

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; that fast path bypasses the per-Read context check, so cancellation is coarse (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. Mode defaults to 0o644 (override with WithMode). A nil root returns ErrUnsafePath.

type SweepResult added in v2.4.0

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

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 CleanupStaleTempsInRoot added in v2.4.0

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 to descend. The two functions differ only in the properties named below, never in how much of the filesystem they touch — 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. 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.

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.

Unlike CleanupStaleTemps this reports counts instead of logging aggregates: it returns every number a caller needs to narrate the outcome itself, so emitting its own summary 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. 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/v2"
)

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())
	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, which is returned exclusively for hard failures (the data did not reach its final path). Two outcomes are deliberately absent from this enum because they are not hard failures: a parent-directory fsync failure (surfaced via Result.Durable) and a preserve-ownership chown failure (best-effort, logged at Warn).

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