fileutil

package
v0.47.8 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package fileutil provides common file operations.

Index

Constants

This section is empty.

Variables

View Source
var ErrPostWriteVerification = errors.New("post-write verification failed")

ErrPostWriteVerification marks a copy that was renamed into place but could not be verified afterward. Callers must treat the destination as written for change tracking while still surfacing the error.

View Source
var ErrSymlinkSkipped = errors.New("symlink skipped")

ErrSymlinkSkipped is returned by CopyFile when the source is a symlink. Callers that walk directories should treat this as "not written" rather than a failure.

View Source
var ErrUnsupportedFileType = errors.New("unsupported file type")

ErrUnsupportedFileType is returned when an operation that copies or hashes file content receives a directory, FIFO, device, socket, or other non-regular filesystem entry. Opening some of these entries can block indefinitely.

Functions

func CanonicalTrustedPath added in v0.45.3

func CanonicalTrustedPath(path string) (string, error)

CanonicalTrustedPath resolves only the platform's documented system aliases (for example macOS /var and /tmp) and rejects an alias that does not point to its expected root-owned directory. It does not resolve arbitrary symlinks. Callers that need a filesystem object must still open the returned path through a descriptor-bound traversal.

func ContentEqual added in v0.12.0

func ContentEqual(path string, srcHash [sha256.Size]byte) (bool, error)

ContentEqual reports whether the file at path has content matching the given SHA-256 hash. Returns false if the file does not exist.

func CopyDir

func CopyDir(ctx context.Context, src, dst string) error

CopyDir recursively copies a directory from src to dst. Destination parents are synchronized once each after the walk, including when a later walk or copy operation fails. Symlinks are skipped with a warning rather than causing an error. A destination at or below the source is rejected before the destination is changed. Other non-regular source entries return ErrUnsupportedFileType. Cancellation stops the walk before its next destination mutation; completed atomic renames are still synchronized before returning.

func CopyDirIfChanged added in v0.12.0

func CopyDirIfChanged(ctx context.Context, src, dst string) ([]string, error)

CopyDirIfChanged recursively copies a directory from src to dst, skipping files whose content has not changed. Returns relative paths of files that were actually written and descendant directories that were created. The destination root itself is never returned. A final file whose atomic rename succeeded before post-write verification failed is returned. Changed destination parents are synchronized once each after the walk, before post-write verification. Both steps still run for completed renames when a later walk or copy operation fails. Symlinks are skipped with a warning rather than causing an error. A destination at or below the source is rejected before the destination is changed. Other non-regular source entries return ErrUnsupportedFileType. Cancellation stops the walk before its next destination mutation; completed atomic renames are still synchronized and verified before returning. The destination root is created when the walk first reaches it, so a call that fails before that — an unreadable source, a rejected source/destination pair — still leaves no destination directory behind.

func CopyDirUnderPinnedRootIfChanged added in v0.45.3

func CopyDirUnderPinnedRootIfChanged(ctx context.Context, src, rootPath, dst string, root *os.Root) ([]string, error)

CopyDirUnderPinnedRootIfChanged is the descriptor-preserving form of CopyDirUnderRootIfChanged. The caller owns root and keeps it open for the complete copy. This is used when a caller has already selected a trusted parent and child directory and must not reopen the destination namespace by path while staging its contents.

func CopyDirUnderRootIfChanged added in v0.45.3

func CopyDirUnderRootIfChanged(ctx context.Context, src, root, dst string) ([]string, error)

CopyDirUnderRootIfChanged is CopyDirIfChanged with every destination mutation resolved from a handle pinned to root, which dst must lie under. It is the directory counterpart of CopyFileUnderRootIfChanged: pinning above the container-writable component keeps dst itself from being swapped for a symlink that redirects the whole tree. A dst outside root is refused rather than copied by path.

root itself is resolved by path when the handle is opened, so root must be a directory the container cannot replace.

The returned paths stay relative to dst, exactly as CopyDirIfChanged's are.

func CopyFile

func CopyFile(ctx context.Context, src, dst string) error

CopyFile copies a single file from src to dst. It creates parent directories if needed and preserves permissions. Uses atomic write via temp file to prevent partial writes on failure. Symlinks are skipped with a warning rather than causing an error. Other non-regular source entries return ErrUnsupportedFileType.

Every destination mutation is resolved by path, so a symlinked directory anywhere in dst redirects the write to the link target. Callers writing into a tree a container can modify must use CopyFileUnderRoot instead.

func CopyFileFromRoot added in v0.45.3

func CopyFileFromRoot(ctx context.Context, root *os.Root, srcName, dst string) error

CopyFileFromRoot copies a regular file selected from a pinned source root into a path-resolved destination. The source lstat, open, and content read all use the supplied root handle; the source pathname is used only for diagnostics and destination-side operations retain CopyFile semantics.

func CopyFileIfChanged added in v0.12.0

func CopyFileIfChanged(ctx context.Context, src, dst string) (bool, error)

CopyFileIfChanged copies src to dst only if the content differs. Returns true if the file was written, false if skipped (content identical). A post-write verification failure returns true together with ErrPostWriteVerification because the atomic rename already happened. Uses SHA-256 content comparison to avoid unnecessary writes on FUSE filesystems. Includes a size-based confidence check to catch FUSE stale-read scenarios where the cached hash appears to match but the actual file content has diverged. Like CopyFile, every destination mutation is resolved by path; use CopyFileUnderRootIfChanged for a destination a container can modify.

func CopyFileUnderRoot added in v0.45.3

func CopyFileUnderRoot(ctx context.Context, src, root, dst string) error

CopyFileUnderRoot copies src to dst with every destination mutation resolved from a handle pinned to root, which dst must lie under. It is CopyFile's contract for a destination a container can modify: a directory swapped for a symlink pointing outside root cannot redirect the write, and a dst that is itself such a symlink is replaced rather than followed. A dst outside root is refused rather than copied by path.

root itself is resolved by path when the handle is opened, so root must be a directory the container cannot replace.

func CopyFileUnderRootIfChanged added in v0.45.3

func CopyFileUnderRootIfChanged(ctx context.Context, src, root, dst string) (bool, error)

CopyFileUnderRootIfChanged is CopyFileIfChanged with the write pinned to root, the way CopyFileUnderRoot pins CopyFile.

The destination hash, byte comparison, write, and post-write verification all use the same pinned root. A comparison reading an attacker-placed file outside root would otherwise find it equal and silently skip the write.

func FileHash added in v0.12.0

func FileHash(path string) ([sha256.Size]byte, error)

FileHash computes the SHA-256 hash of a file's contents. Returns the hash as a byte slice, or an error if the file cannot be read. Non-regular entries return ErrUnsupportedFileType before content is read.

func OpenPinnedRoot added in v0.45.3

func OpenPinnedRoot(path string, create bool) (*os.Root, error)

OpenPinnedRoot opens a directory without following a symlink in the root or any ancestor. Every component is selected through the descriptor for its parent; no path-based validation is followed by a path-based reopen. When create is true, missing components are created through the same parent handle before they are opened and identity-checked.

func OpenRegularNoFollow added in v0.45.3

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

OpenRegularNoFollow opens path without following a final-component symlink and without blocking on a FIFO, then validates the opened descriptor. Reading from the returned file therefore reads the entry that was checked.

func OpenRootRegular added in v0.45.3

func OpenRootRegular(root *os.Root, name string, followSymlinks bool) (*os.File, error)

OpenRootRegular opens a file relative to a previously pinned root and validates the descriptor. With followSymlinks false, a final-component symlink is refused; with true, os.Root still prevents the resolved path from escaping the pinned root. In both modes a special file is rejected before the caller reads it.

func PinnedRootFS added in v0.45.3

func PinnedRootFS(root *os.Root) fs.FS

PinnedRootFS exposes a pinned root as an fs.FS for callers that need a descriptor-bound namespace. Directory entries are materialized with Root.Lstat so their metadata does not lazily reopen a replaced pathname.

Types

This section is empty.

Jump to

Keyboard shortcuts

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