filesafe

package module
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 17 Imported by: 4

README

filesafe

Go Reference Go version

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

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

Why use it

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

  • Every write syncs the file and makes its rename durable, and Result.Durable reports whether every sync succeeded.
  • A nil error means the new data is at the path. Any other error leaves the old file in place. A failure once the temp file is being created is a *WriteError naming the step that failed, and a refusal before it, such as a bad argument, a cancelled context or an over-cap size, is a plain error matching its sentinel.
  • WithMode proves the mode the filesystem stored, so a filesystem that widens a 0600 request fails the write instead of publishing a readable file. It is not available on Windows.
  • The *InRoot functions run through an *os.Root, so a symlink or .. in a name cannot leave the directory tree.
  • Writes refuse a symlink, FIFO, socket or device node at the target path.

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

Install

go get github.com/cplieger/go/filesafe@latest

Usage

package main

import (
	"context"
	"log"
	"os"

	"github.com/cplieger/go/filesafe"
)

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

	// Replace a file. Result.Durable reports whether the new content
	// survives a power loss.
	res, err := filesafe.WriteFile(ctx, "/var/lib/myapp/state.json", []byte(`{"ok":true}`))
	if err != nil {
		log.Fatal(err)
	}
	if !res.Durable {
		log.Printf("%s is written but not yet durable", res.Path)
	}

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

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

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

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

API

  • Writes: WriteFile, WriteReader, NewPendingFile and their *InRoot forms.
  • Reads: ReadBounded, ReadBoundedFile, ReadBoundedInRoot, OpenRegularNoFollow, OpenRegularInRoot, OpenRegularInRootNoFollow.
  • Shared directory trees: WalkDirInRoot, OpenParentInRoot, RemoveFileInRoot.
  • Modes: EnforceMode, EnsurePrivateDir.
  • Temp files and checks: CleanupStaleTemps, CleanupStaleTempsInRoot, TempName, IsPackageTemp, ProbeWritable, ProbeWritableInRoot, ValidatePath, and Identify with FileIdentity.
  • Options: WithMode, WithMkdirMode, WithMkdirAll and WithMaxBytes for writes and probes (WriteOption), WithRecursive for sweeps (SweepOption), WithRepairOwnedDir for EnsurePrivateDir (PrivateDirOption), and WithLogger, which all of them take (Option).
  • Results and errors: Result, SweepResult, ProbeResult with its ProbePhase, PrivateDirResult, sentinel values for errors.Is, ErrInvalidArgument, ErrFileBusy and ErrModeUnsupported among them, and *WriteError with its WritePhase and *NotRegularError for errors.As.

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

What a nil error means

Every write creates a temp file in the target's directory, writes and syncs it, renames it over the target, then syncs the directory. Windows has no directory sync, so there the write flushes the published file instead. After a crash the path holds the complete old content or the complete new content.

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

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

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

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

File modes

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

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

WithMkdirMode creates missing parent directories at a mode it also proves, and WithMkdirAll(true) creates them as os.MkdirAll does, proving nothing. EnsurePrivateDir sets up one directory level that only the effective user may enter. File modes and private directories explains both.

Windows

The writes, the reads, the sweeps and the probes work on Windows (amd64 and arm64). filesafe never calls os.Rename, which on Windows gives no atomic-replace guarantee (golang/go#22397). It renames through *os.Root, which issues one FileRenameInformationEx call with FILE_RENAME_REPLACE_IF_EXISTS and FILE_RENAME_POSIX_SEMANTICS. That call replaces the target in one step, even while other processes hold it open, as long as their handles allow deletion (FILE_RENAME_INFORMATION).

These limits apply on Windows:

  • A target another process holds open without delete sharing cannot be replaced while that handle stays open. os.Open and os.ReadFile in any Go program open files that way, and so do many editors, backup tools and virus scanners. The write retries 7 times over about 0.6 seconds, then fails with a *WriteError in PhaseRename matching ErrFileBusy. A cancelled context ends the retry early. ReadBounded, ReadBoundedInRoot, OpenRegularNoFollow, OpenRegularInRoot and OpenRegularInRootNoFollow, like any open through an *os.Root, allow deletion and never block a write.
  • ErrFileBusy also covers an access-denied refusal, because Windows reports a file held open and a refusing ACL with the same error. The wrapped syscall.Errno tells which.
  • Go renames without POSIX semantics when a filesystem refuses them. That rename is still atomic, but it is refused while any handle is open on the target, even one that allows deletion, so the write retries and fails with ErrFileBusy as above.
  • A target with the read-only attribute is refused before anything is written, with an error matching fs.ErrPermission.
  • WithMode and WithMkdirMode with a nonzero mode, EnforceMode and EnsurePrivateDir return ErrModeUnsupported before anything is created. A zero mode is ErrInvalidArgument there as everywhere. Go's chmod on Windows only sets the read-only attribute, and access is governed by the ACL the new file inherits from its directory. WithMkdirAll(true) creates a missing parent directory there.
  • There is no directory sync. On a local NTFS volume the write flushes the published file after the rename, which also persists the rename. On ReFS, FAT, exFAT and network shares nothing documents that, so Result.Durable is false there, and the package logs that at Info once per volume for the life of the process. A share or mapped drive counts as a network share even when its server's volume is NTFS.
  • A symlink at the target is refused with ErrSymlinkTarget, as on Linux. A junction or any other reparse point, such as a cloud-sync placeholder, is refused with ErrNotRegular.
  • An absolute path starts with a drive letter (C:\) or is a UNC path (\\server\share\). A rooted path such as \data and a drive-relative path such as C:data are refused with ErrUnsafePath, and so is either form as a root-relative name.
  • A stale temp file another process holds open without delete sharing cannot be removed. The sweep counts it in Failed and leaves it for a later sweep.

Unsupported by design

These are deliberate non-goals, not missing features.

  • fs.FS interop. fs.FS is a read-only interface, and atomic writes are outside its scope.
  • Atomic symlink replacement. Use google/renameio for that.
  • Detecting a cross-mount temp directory. Temp files are always created in the target's own directory, on the same mount, which is the only correct place for an atomic rename.

Documentation

Credits

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

Contributing

See CONTRIBUTING.md.

Disclaimer

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

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

License

Apache-2.0. See LICENSE.

Documentation

Overview

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

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

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// ErrEmptyPath is returned when a path argument is empty.
	ErrEmptyPath = errors.New("filesafe: empty path")
	// ErrUnsafePath is returned when a path fails the local safety check, and
	// when a function is given a nil *os.Root or *os.File: every function
	// taking one refuses nil with an error matching it.
	ErrUnsafePath = errors.New("filesafe: unsafe path")
	// ErrInvalidArgument is returned for an argument no call could mean: a
	// non-positive sweep maxAge, a negative read maxBytes, WithMode(0) or
	// WithMkdirMode(0), and a nil reader or walk function. Nothing is created
	// or removed first. Match with errors.Is.
	ErrInvalidArgument = errors.New("filesafe: invalid argument")
	// 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("filesafe: file too large")
	// ErrSymlinkTarget is returned when the target path is a symlink, which
	// every write entry point, OpenRegularNoFollow, OpenRegularInRootNoFollow
	// and EnsurePrivateDir refuse, and by OpenParentInRoot (so
	// RemoveFileInRoot) for a symlinked ancestor of the name.
	ErrSymlinkTarget = errors.New("filesafe: target is a symlink")
	// ErrRaced is returned when a name changed between a check and the open
	// that followed it, so the check could not be shown to cover what was
	// opened: by OpenRegularInRootNoFollow for the name it refused a symlink
	// at, and by OpenParentInRoot (so RemoveFileInRoot) for an ancestor
	// directory. 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("filesafe: path changed between the check and the open")
	// ErrNotRegular is returned when a name resolves to something other than a
	// regular file. ReadBounded, ReadBoundedInRoot, OpenRegularNoFollow,
	// OpenRegularInRoot and OpenRegularInRootNoFollow refuse 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("filesafe: not a regular file")
	// ErrNotDirectory is returned by EnsurePrivateDir when the name is occupied
	// by something other than a directory, and by OpenParentInRoot for an
	// ancestor of the name that is neither a directory nor a symlink. Match
	// with errors.Is.
	ErrNotDirectory = errors.New("filesafe: 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("filesafe: 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("filesafe: directory mode grants group or other access")
	// ErrModeNotStored is returned when the mode read back after a chmod does
	// not match what was requested, a mount property rather than a permission
	// error: by EnforceMode, by a write or probe under WithMode or
	// WithMkdirMode, and by EnsurePrivateDir. Match with errors.Is.
	ErrModeNotStored = errors.New("filesafe: filesystem did not store the requested mode")
	// ErrAborted is returned by PendingFile.Commit when the pending file was
	// already aborted by a prior Cleanup or Close.
	ErrAborted = errors.New("filesafe: pending file aborted")
	// ErrFileBusy is returned on Windows when the replace was refused through
	// every retry, or the context ended while waiting to retry. It arrives
	// inside a *WriteError with PhaseRename, wrapping the last refusal's
	// syscall.Errno (and the context error, if any): ERROR_SHARING_VIOLATION
	// or ERROR_LOCK_VIOLATION means another handle held the file, while
	// ERROR_ACCESS_DENIED is either such a handle or an ACL refusal, which
	// Windows reports the same way. Match with errors.Is.
	ErrFileBusy = errors.New("filesafe: target in use or access denied")
	// ErrModeUnsupported is returned on Windows by EnforceMode,
	// EnsurePrivateDir and any write or probe given a nonzero WithMode or
	// WithMkdirMode, before anything is created: Go's chmod there only sets the
	// read-only attribute. A zero mode is ErrInvalidArgument on every platform.
	// Match with errors.Is.
	ErrModeUnsupported = errors.New("filesafe: file modes are not supported on this platform")
)

Functions

func EnforceMode

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

EnforceMode sets want on the open file or directory f (fchmod), reads the mode back from the same handle (fstat) and returns what the filesystem stored: a mode given to mkdir or open is only a request, which the umask narrows and an inheritable ACL can widen (docs/file-modes.md). Only the permission, setuid, setgid and sticky bits are compared. A mismatch returns ErrModeNotStored with the stored mode; other errors are the filesystem's. A nil f returns ErrUnsafePath. On Windows it returns ErrModeUnsupported and leaves f unchanged.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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 := filesafe.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. The prefix names the module this package grew from and is kept, so the sweeps still reclaim the temps that module left and an alert matching the shape still fires. It and TempName exist so a caller, or its tests, can plant or recognise a temp the sweeps reclaim without spelling the shape out.

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 and a denied one fs.ErrPermission. A component that is a symlink matches ErrSymlinkTarget, one that is any other non-directory matches ErrNotDirectory, and one that changed while it was being opened matches ErrRaced, the one refusal a retry can cure; each names the component. An empty name is ErrEmptyPath; an absolute or NUL-holding name, ".", ".." and a nil root are ErrUnsafePath.

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 with that descriptor's FileInfo, refusing anything not a regular file with ErrNotRegular naming the mode. An in-root symlink resolves; OpenRegularInRootNoFollow refuses one. The caller owns the file and root. A relative, NUL-free name is required (ErrEmptyPath, ErrUnsafePath), a nil root returns ErrUnsafePath, and other errors are the root's own.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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 := filesafe.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 := filesafe.Identify(info)
	data, _ := filesafe.ReadBoundedFile(context.Background(), f, 1<<20)
	fmt.Println(len(data), id.Recorded())
}
Output:
12 true

func OpenRegularInRootNoFollow

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

OpenRegularInRootNoFollow is OpenRegularInRoot that refuses a symlink at the final component with ErrSymlinkTarget instead of resolving it. A name whose identity changes between the check and the open is ErrRaced. It is a separate function so that no zero-value option selects the permissive policy. Ancestor components are not pinned (see OpenParentInRoot).

func OpenRegularNoFollow

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

OpenRegularNoFollow opens the absolute path read-only and returns the open descriptor with that descriptor's FileInfo, refusing anything not a regular file with ErrNotRegular naming the mode, and a symlink at the final component with ErrSymlinkTarget: the NoFollow suffix means the same as on OpenRegularInRootNoFollow. Ancestor components are not pinned, and the open is non-blocking so a FIFO cannot stall the caller. An empty, NUL-holding or relative path is ErrEmptyPath or ErrUnsafePath; other errors are the filesystem's own (a missing file matches fs.ErrNotExist). On Windows the open handle does not block a filesafe write of the file.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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 := filesafe.OpenRegularNoFollow(target)
	if err == nil {
		f.Close()
	}
	fmt.Println("regular file:", err)

	// The open itself refuses a symlink under the name, so there is no
	// check-then-open window. ReadBounded still follows links by design.
	_, _, err = filesafe.OpenRegularNoFollow(link)
	fmt.Println("symlink:", errors.Is(err, filesafe.ErrSymlinkTarget))
}
Output:
regular file: <nil>
symlink: true

func ReadBounded

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

ReadBounded opens path and reads at most maxBytes from it, returning 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. Only regular files are read: a directory, named pipe, device node or socket is refused with ErrNotRegular, and the open is non-blocking so a FIFO with no writer cannot stall the caller. It follows symlinks, unlike the write primitives: a caller reading from a directory a less-trusted principal can write uses ReadBoundedInRoot. On Windows its open handle does not block a filesafe write of the file.

maxBytes 0 admits only an empty file, and a negative maxBytes returns ErrInvalidArgument: a read bound is never "no cap", unlike WithMaxBytes.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "data.txt")
	_ = os.WriteFile(path, []byte("bounded"), 0o644)
	data, _ := filesafe.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 is ReadBounded for a file the caller opened itself, for example through an *os.Root to confine the path: it reads at most maxBytes from f and 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. A nil f returns ErrUnsafePath, and maxBytes follows ReadBounded's rule.

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. A nil root returns ErrUnsafePath, and maxBytes follows ReadBounded's rule.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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, _ := filesafe.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. The refusal is a check before the unlink, and os.Root has no unlink that refuses a directory, so an empty directory a racing writer swaps in after the check can be removed. 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. The parent's refusals are OpenParentInRoot's.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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 := filesafe.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, as this package's own writes do.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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, filesafe.TempName())
	_ = os.WriteFile(path, []byte("mine"), 0o600)
	old := time.Now().Add(-2 * time.Hour)
	_ = os.Chtimes(path, old, old)

	res, _ := filesafe.CleanupStaleTemps(context.Background(), dir, time.Hour)
	fmt.Println(filesafe.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. It runs the same check those entry points run, 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 hands every entry of root's tree to fn as fs.WalkDir does: root-relative, slash-separated on every OS, the root first as ".", then pre-order; a directory that cannot be opened or read is reported in a second call for its own path with its DirEntry and the error, and only a failed stat of the root itself passes a nil DirEntry; fs.SkipDir and fs.SkipAll as usual. It never descends a symlinked directory, refuses a non-directory swapped in for one, and keeps one directory handle open. Unlike fs.WalkDir, a directory's entries all arrive before its subdirectories are walked, sorted only within a batch of 256, and the walk stops between batches once ctx is done. The caller owns root (docs/confinement.md). A nil root returns ErrUnsafePath and a nil fn ErrInvalidArgument.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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
	_ = filesafe.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 holds, so a cache can tell from a stat alone whether its copy is still current. Matches needs both an equal mtime and os.SameFile: an in-place write can keep the mtime, and a publish by rename can carry an old one. It does not compare size; a caller whose file is also rewritten in place keeps its own size check (docs/reload-staleness.md). The zero value records nothing and matches nothing. What to do about a change stays with the caller. Test whether one was recorded with Recorded, not by comparing with FileIdentity{}.

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 matches no later stat. On Windows it records the file at the path when Identify runs, so call it right after the stat.

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 device and inode, or volume and file index on Windows). An unrecorded identity matches nothing, and a nil info (no file observed) matches nothing.

func (FileIdentity) Recorded

func (id FileIdentity) Recorded() bool

Recorded reports whether an identity was captured at all. A zero FileIdentity (nothing loaded yet, or a load that failed before its stat) records nothing.

type NotRegularError

type NotRegularError struct {
	// Name is the path or root-relative name as the caller supplied it, cleaned.
	Name string
	// Mode is the full FileMode of what was actually there. Type() names the
	// kind; the permission bits are kept because a caller reporting an
	// unexpected object usually wants both.
	Mode os.FileMode
}

NotRegularError reports that a name resolved to something other than a regular file, and carries the mode that decided it.

The mode is a DIAGNOSTIC a caller reports, and reading it out of a message string is not something a caller should have to do. Every producer here returns one, so a caller resolving a name once never has to stat the path a second time just to describe a refusal. It unwraps to ErrNotRegular, so errors.Is keeps matching for callers that only need the verdict.

func (*NotRegularError) Error

func (e *NotRegularError) Error() string

Error renders the verdict, the name and the kind of file found.

func (*NotRegularError) Unwrap

func (*NotRegularError) Unwrap() error

Unwrap returns ErrNotRegular, so errors.Is matches the verdict.

type Option

type Option interface {
	WriteOption
	SweepOption
	PrivateDirOption
}

Option is accepted by every operation that takes options: WithLogger is the one option that applies to writes, probes, sweeps and EnsurePrivateDir alike. Every other option has its operation's own type, so passing it to an operation it does not configure is a compile error.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets the logger an operation reports to. A nil logger, or no WithLogger at all, uses slog.Default().

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; Name reports the temp's path, so the staged file can be checked before Commit. Write, WriteString and ReadFrom enforce WithMaxBytes and count BytesWritten; other writes through the embedded file escape the count but not the cap, which Commit re-checks. NewPendingFile owns the root it opens and closes it at Commit or a successful Cleanup. Close is Cleanup, so a deferred Close aborts an uncommitted write instead of leaking its temp. A PendingFile is not safe for concurrent use. Create one with NewPendingFile or NewPendingFileInRoot; the zero value is not usable.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "pending.txt")
	pf, _ := filesafe.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 ...WriteOption) (*PendingFile, error)

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

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "pending.txt")
	pf, _ := filesafe.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 ...WriteOption) (*PendingFile, error)

NewPendingFileInRoot is NewPendingFile for name, a path relative to root, with WriteFileInRoot's confinement; the lifecycle is identical. File mode: see WithMode. The caller owns root and must keep it open for the PendingFile's lifetime; a caller-provided root is never closed. Result.Path is root's directory joined with the cleaned relative name. A nil root returns ErrUnsafePath.

Example
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/cplieger/go/filesafe"
)

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, _ := filesafe.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) Close

func (p *PendingFile) Close() error

Close aborts the pending write exactly as Cleanup does and returns Cleanup's error, so a habitual defer p.Close() never leaks the temp or the root NewPendingFile opened; after Commit it does nothing. It replaces the embedded file's Close: p.File.Close drops only the descriptor, and a Commit after it fails.

func (*PendingFile) Commit

func (p *PendingFile) Commit(ctx context.Context) (Result, error)

Commit runs the durability barrier (WithMaxBytes size check, WithMode enforcement, fsync) and publishes the temp at the target as WriteFile does. It is idempotent; after Cleanup it returns ErrAborted, and after it Cleanup is a no-op. A ctx cancelled before the rename aborts and removes the temp; on Windows it also ends the retry of a busy target with ErrFileBusy.

func (*PendingFile) Name

func (p *PendingFile) Name() string

Name reports the temp file's path, cleaned, so a root opened through OpenParentInRoot, whose own Name keeps a "/." the open added, does not carry it into the temp's path. The path is cleaned lexically (filepath.Clean), as Result.Path is joined, so a root opened through a symlink followed by ".." is named as written, not as resolved.

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 PrivateDirOption

type PrivateDirOption interface {
	// contains filtered or unexported methods
}

PrivateDirOption configures EnsurePrivateDir. Only this package's options implement it.

func WithRepairOwnedDir

func WithRepairOwnedDir(repair bool) PrivateDirOption

WithRepairOwnedDir makes EnsurePrivateDir chmod a pre-existing directory to 0700 instead of refusing it with ErrModeTooOpen. The repair is sound because ownership by the effective uid is proved first, and every other refusal still fires. It is not the default because a wide mode on an owned directory can be deliberate. PrivateDirResult.Repaired reports whether a repair happened.

type PrivateDirResult

type PrivateDirResult struct {
	// Mode is the mode the filesystem actually stored, read back from the
	// open handle (permission bits plus setuid/setgid/sticky). Always 0700
	// 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 this call chmod'ed the directory to 0700: a
	// Created directory whose stored mode was not what was asked (an
	// inheritable ACL widening a fresh 0700 directory), which is always
	// repaired, or, under WithRepairOwnedDir, a pre-existing owned directory
	// that granted group or other access.
	Repaired bool
}

PrivateDirResult 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 ...PrivateDirOption) (PrivateDirResult, error)

EnsurePrivateDir creates the one absolute directory level dir at 0700 if absent, then proves from an open handle that it is a directory owned by the effective uid with no group or other access; dir's parent is not checked, and the verdict holds at one point in time (docs/file-modes.md). A pre-existing too-open directory is ErrModeTooOpen unless WithRepairOwnedDir; other refusals are ErrEmptyPath, ErrUnsafePath, ErrSymlinkTarget, ErrNotDirectory, ErrNotOwned and ErrModeNotStored (match with errors.Is). On Windows a valid dir returns ErrModeUnsupported.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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 := filesafe.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, _ := filesafe.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/go/filesafe"
)

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 := filesafe.EnsurePrivateDir(link)
	fmt.Println("symlink:", errors.Is(err, filesafe.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 = filesafe.EnsurePrivateDir(shared)
	fmt.Println("group/other access:", errors.Is(err, filesafe.ErrModeTooOpen))
}
Output:
symlink: true
group/other access: true

type ProbePhase

type ProbePhase int

ProbePhase 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. It is the probe's counterpart to WritePhase. The probe reports the phase and leaves the pass/fail policy to the caller; ProbeResult.Writable names the phases that mean only teardown failed.

const (
	// ProbePhaseNone is the zero value: every phase passed.
	ProbePhaseNone ProbePhase = iota
	// ProbePhaseMkdir indicates the directory could not be created, or that
	// under WithMkdirMode a created level did not store the mode (Err matches
	// ErrModeNotStored). Only reachable with WithMkdirMode or WithMkdirAll;
	// without either a missing directory fails at ProbePhaseCreate, exactly
	// as a write to a missing parent does.
	ProbePhaseMkdir
	// ProbePhaseCreate 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.
	ProbePhaseCreate
	// ProbePhaseWrite indicates the first data write to the probe file failed
	// (a quota or a full filesystem, which the create alone does not reveal).
	ProbePhaseWrite
	// ProbePhaseSync indicates flushing the probe file failed, the delayed
	// error a network filesystem reports at fsync rather than at write.
	ProbePhaseSync
	// ProbePhaseClose indicates closing the probe file failed, the other
	// place a deferred write error surfaces.
	ProbePhaseClose
	// ProbePhaseRemove 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.
	ProbePhaseRemove
)

func (ProbePhase) String

func (s ProbePhase) String() string

String names the phase in the words a log line uses.

type ProbeResult

type ProbeResult struct {
	// Err is the failure from Phase, 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
	// Phase is the first phase that failed, or ProbePhaseNone when all passed.
	Phase ProbePhase
	// Leaked reports whether the probe file is still on disk. It can be true
	// only alongside ProbePhaseRemove, or alongside ProbePhaseWrite,
	// ProbePhaseSync or ProbePhaseClose 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 phase failure arrives here, never as the probe function's error return, so the caller decides which phases are fatal. A caller that wants pass/fail asks OK once.

It is only meaningful alongside a nil error: a non-nil error means no probe ran, and OK and Writable on the zero ProbeResult returned with it are not a verdict.

func ProbeWritable

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

ProbeWritable proves dir is writable by doing what an atomic write does (create a TempName file, write and flush a byte, close, unlink) and reports the first failed phase in the ProbeResult; a non-nil error means the probe could not start (empty dir, done ctx, a refused mode option). dir may be relative; a missing dir fails at ProbePhaseCreate unless WithMkdirMode or WithMkdirAll creates it, through the same chain a write uses. WithMode makes it prove an owner-only staging file; on Windows either mode option with a nonzero mode returns ErrModeUnsupported. ctx is checked once, a started probe always cleans up, and CleanupStaleTemps reclaims a leftover.

Example
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/cplieger/go/filesafe"
)

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)

	res, err := filesafe.ProbeWritable(context.Background(), dir)
	if err != nil {
		return // the probe could not be attempted (empty dir, cancelled ctx)
	}
	// The phase 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.Phase, res.Err)
	case !res.OK():
		fmt.Println("writable, but cleanup failed:", res.Phase, "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(filesafe.IsPackageTemp(res.Name))
}
Output:
writable, nothing left behind
true

func ProbeWritableInRoot

func ProbeWritableInRoot(ctx context.Context, root *os.Root, name string, opts ...WriteOption) (ProbeResult, error)

ProbeWritableInRoot is ProbeWritable confined to root's tree: name is relative to root ("." for root itself) and every operation runs through the *os.Root, so an escaping name is refused and reported at ProbePhaseCreate (ProbePhaseMkdir under WithMkdirMode or WithMkdirAll). Everything else, the WithMode rule included, is ProbeWritable's. The caller owns root and keeps it open; a nil root returns ErrUnsafePath.

Example
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/cplieger/go/filesafe"
)

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, _ := filesafe.ProbeWritableInRoot(context.Background(), root, ".")
	fmt.Println(res.OK(), res.Leaked)

	// An escaping name is refused by the root, reported as a phase failure.
	escaped, _ := filesafe.ProbeWritableInRoot(context.Background(), root, "../outside")
	fmt.Println(escaped.Phase, escaped.Writable())
}
Output:
true false
create probe file false

func (ProbeResult) OK

func (r ProbeResult) OK() bool

OK reports whether every phase 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. It names those phases, so a phase added later is not writable unless it says so here.

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, its directory, and every directory this
	// write created were flushed, and on the absolute-path writes also
	// every level a racing writer created after the write found it missing
	// (docs/durability.md, per platform). False means the data
	// is present at Path but may not survive an immediate power loss, and
	// the cause is logged.
	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 ...WriteOption) (Result, error)

WriteFile atomically writes data to path. File mode: see WithMode. A nil error means the data is at path; check Result.Durable for crash durability.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "data.txt")
	res, _ := filesafe.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/go/filesafe"
)

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "nested", "dir", "file.txt")
	_, _ = filesafe.WriteFile(context.Background(), path, []byte("deep"),
		filesafe.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/go/filesafe"
)

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "secret.txt")
	_, _ = filesafe.WriteFile(context.Background(), path, []byte("s3cr3t"),
		filesafe.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 ...WriteOption) (Result, error)

WriteFileInRoot is WriteFile for name, a path relative to root: every filesystem operation runs through the *os.Root, so a symlink or ".." component in name can never write outside root's tree. File mode: see WithMode. A nil error means the data is at name; check Result.Durable for crash durability. Result.Path is root's directory joined with the cleaned relative name. A nil root returns ErrUnsafePath.

Example
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/cplieger/go/filesafe"
)

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+).
	_, _ = filesafe.WriteFileInRoot(context.Background(), root, "rooted.txt",
		[]byte("confined"))
	f, _ := root.Open("rooted.txt")
	defer func() { _ = f.Close() }()
	data, _ := filesafe.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 ...WriteOption) (Result, error)

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

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "stream.txt")
	_, _ = filesafe.WriteReader(context.Background(), path,
		strings.NewReader("streamed"))
	data, _ := os.ReadFile(path)
	fmt.Println(string(data))
}
Output:
streamed
Example (WithMode)
package main

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

	"github.com/cplieger/go/filesafe"
)

func main() {
	dir, _ := os.MkdirTemp("", "example")
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "stream.txt")
	_, _ = filesafe.WriteReader(context.Background(), path,
		strings.NewReader("streamed"), filesafe.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 ...WriteOption) (Result, error)

WriteReaderInRoot atomically writes the contents of r to name, a path relative to root, confined to root's tree (see WriteFileInRoot). If r implements io.WriterTo it is used for efficient copying, so cancellation is coarse on that path. File mode: see WithMode. A nil root returns ErrUnsafePath and a nil r ErrInvalidArgument.

type SweepOption

type SweepOption interface {
	// contains filtered or unexported methods
}

SweepOption configures CleanupStaleTemps and CleanupStaleTempsInRoot. Only this package's options implement it.

func WithRecursive

func WithRecursive(recursive bool) SweepOption

WithRecursive makes CleanupStaleTemps and CleanupStaleTempsInRoot descend into subdirectories. It is off by default because a sweep deletes files, so its reach is stated at the call site. A temp sits beside its target, so a write to out/example.com/cert.pfx leaves its orphan in out/example.com, which only a recursive sweep of out/ finds.

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 ...SweepOption) (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 returns ErrInvalidArgument and sweeps nothing, so a zero value from an unset config can neither empty a directory nor turn the sweep off unseen. An empty dir returns ErrEmptyPath. dir may be relative; a dir that does not exist is a sweep with nothing to reclaim.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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, _ := filesafe.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 ...SweepOption) (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 returns ErrInvalidArgument and sweeps nothing. 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. A nil root returns ErrUnsafePath.

Example
package main

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

	"github.com/cplieger/go/filesafe"
)

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, _ := filesafe.CleanupStaleTempsInRoot(context.Background(), root, time.Hour, filesafe.WithRecursive(true))
	fmt.Println(res.Removed, res.Failed, res.Unreadable)
}
Output:
1 0 0

type WriteError

type WriteError struct {
	// Err is the failure, matched through Unwrap.
	Err error
	// Phase is the step of the write that failed.
	Phase WritePhase
}

WriteError wraps a failure inside an atomic write, once its temp file is being created, with the phase that failed. A WriteError always means the data did NOT reach its final path. A refusal before that point (an invalid argument or option, a done context, an over-cap size, a target that is a symlink or not a regular file, a parent directory that could not be created) is a plain error matching its sentinel instead.

func (*WriteError) Error

func (e *WriteError) Error() string

Error renders "filesafe: <phase>: <cause>". A nil Err renders as "no cause", so a WriteError built by hand never panics.

func (*WriteError) Unwrap

func (e *WriteError) Unwrap() error

Unwrap returns Err.

type WriteOption

type WriteOption interface {
	// contains filtered or unexported methods
}

WriteOption configures an atomic write (WriteFile, WriteReader, NewPendingFile and their InRoot forms) or a writability probe (ProbeWritable, ProbeWritableInRoot). A probe does what a write does, so it takes the options of the write it stands in for: pass it the same slice. Only this package's options implement it.

func WithMaxBytes

func WithMaxBytes(n int64) WriteOption

WithMaxBytes caps the content an atomic write stages, the write-side mirror of ReadBounded's bound. WriteFile and WriteFileInRoot refuse over-cap data before creating the temp; WriteReader, WriteReaderInRoot and a PendingFile refuse, whole, the chunk or call that would cross the cap. The barrier rechecks the staged file's size, so bytes staged through WriteAt or after a Seek cannot publish over the cap. Every refusal matches ErrFileTooLarge and leaves the old target intact. n <= 0 means no cap. A probe stages one byte, so no cap refuses it.

func WithMkdirAll

func WithMkdirAll(create bool) WriteOption

WithMkdirAll with create true makes a write or probe create missing parent directories first, as os.MkdirAll does: 0777 through the umask and any inherited ACL, with no mode chmod'ed or checked, on every platform. Each created directory is synced into its parent where the platform syncs directories; on Windows the write's flush of the published file persists them on local NTFS, and Result.Durable is false on other volumes. Use WithMkdirMode instead for a directory whose readers must be restricted. WithMkdirAll(false) creates nothing. Either way it and WithMkdirMode replace each other; the last call wins.

func WithMkdirMode

func WithMkdirMode(mode os.FileMode) WriteOption

WithMkdirMode creates missing parent directories at mode before writing; without it a missing parent is an error. The mode is enforced on each created directory (a pre-existing one is never chmod'ed), or the write fails with ErrModeNotStored. It governs directories only; the file's mode is WithMode's. Result.Durable is false if a created directory's parent fsync failed. A zero mode returns ErrInvalidArgument before creating anything, on every platform; WithMkdirAll(false) is the way to create no directories. On Windows a write or probe given a nonzero mode returns ErrModeUnsupported before creating anything; use WithMkdirAll there. It and WithMkdirAll replace each other; the last call wins.

func WithMode

func WithMode(mode os.FileMode) WriteOption

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

Without it the file is ordinary: created like os.Create (0666 through the umask and inherited ACLs) and never chmod'ed or checked. Pass it for any file whose readers must be restricted. A zero mode would publish a file nobody but root can read, so a write or probe given WithMode(0) returns ErrInvalidArgument before creating anything, on every platform. On Windows a write or probe given a nonzero mode returns ErrModeUnsupported before creating anything.

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), creating the temp file inside it, or, under
	// WithMode, proving the new temp owner-only before any data is written.
	PhaseTempCreate WritePhase = iota + 1
	// PhaseTempWrite indicates failure writing to the temp file.
	PhaseTempWrite
	// PhaseTempChmod indicates failure enforcing WithMode's final mode on the
	// written temp file; it occurs only under WithMode.
	PhaseTempChmod
	// PhaseTempSync indicates failure syncing the temp file.
	PhaseTempSync
	// PhaseTempClose indicates failure closing the temp file.
	PhaseTempClose
	// PhaseRename indicates failure renaming temp to the final path.
	PhaseRename
)

func (WritePhase) String

func (p WritePhase) String() string

String names the phase in the words a WriteError's message uses.

Jump to

Keyboard shortcuts

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