fileutil

package
v0.3.0-beta.32 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package fileutil provides shared filesystem helpers for Compozy components.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrTargetExists reports an atomic no-replace publication collision.
	ErrTargetExists = errors.New("fileutil: target exists")
	// ErrAtomicNoReplaceUnsupported reports a platform without an atomic
	// no-replace directory rename primitive. The operation is not attempted.
	ErrAtomicNoReplaceUnsupported = errors.New("fileutil: atomic no-replace directory move is unsupported")
	// ErrMoveSourceIdentityChanged reports that the path named as a move source
	// no longer refers to the entry retained by the supplied capability.
	ErrMoveSourceIdentityChanged = errors.New("fileutil: move source identity changed")
	// ErrDirectoryMoveRecoveryRequired reports that an uncommitted move could
	// not restore its source name from the private transaction directory.
	ErrDirectoryMoveRecoveryRequired = errors.New("fileutil: directory move recovery required")
	// ErrMoveRecoveryEntryNotFound reports that a retained entry left its private transaction.
	ErrMoveRecoveryEntryNotFound = errors.New("fileutil: move recovery entry not found")
)
View Source
var (
	// ErrSymlink reports a symlink or platform reparse point in a protected path.
	ErrSymlink = errors.New("fileutil: symlink or reparse point")
	// ErrDirectory reports a directory where a regular file is required.
	ErrDirectory = errors.New("fileutil: directory")
	// ErrNotDirectory reports a non-directory where a directory is required.
	ErrNotDirectory = errors.New("fileutil: not a directory")
	// ErrNotRegular reports a special file where a regular file is required.
	ErrNotRegular = errors.New("fileutil: not a regular file")
	// ErrDirectoryDurabilityUnconfirmed reports that the platform rejected a
	// directory metadata flush, so persistence cannot be confirmed.
	ErrDirectoryDurabilityUnconfirmed = errors.New("fileutil: directory metadata durability unconfirmed")
)
View Source
var (
	// ErrTarGzipCompressedLimit reports that the compressed stream exceeded its byte budget.
	ErrTarGzipCompressedLimit = errors.New("fileutil: tar gzip compressed size limit exceeded")
	// ErrTarSizeLimit reports that the raw tar stream exceeded its byte budget.
	ErrTarSizeLimit = errors.New("fileutil: tar size limit exceeded")
	// ErrTarFileCountLimit reports that the archive exceeded its entry budget.
	ErrTarFileCountLimit = errors.New("fileutil: tar file count limit exceeded")
)
View Source
var ErrInvalidPath = errors.New("fileutil: invalid path")

ErrInvalidPath reports a path that cannot be represented safely by the filesystem boundary.

View Source
var ErrPathOutsideRoot = errors.New("fileutil: resolved path is outside root")

ErrPathOutsideRoot identifies a path whose resolved target escapes the resolved root.

View Source
var ErrPathRootRequired = errors.New("fileutil: root path is required")

ErrPathRootRequired reports a blank root in a containment request.

Functions

func AtomicRemoveFile

func AtomicRemoveFile(path string) (err error)

AtomicRemoveFile removes a file and syncs its parent directory.

func AtomicWrite

func AtomicWrite(path string, content []byte) error

AtomicWrite writes content with the default Compozy file permissions via temp-file-and-rename.

func AtomicWriteFile

func AtomicWriteFile(path string, content []byte, perm os.FileMode) (err error)

AtomicWriteFile writes content to path via a temp file plus atomic replacement. It always syncs the temp file before replacement. Parent-directory metadata durability remains best-effort on platforms without directory fsync support.

func AtomicWritePrivateFile

func AtomicWritePrivateFile(path string, contents []byte) (err error)

AtomicWritePrivateFile validates inherited protection before writing a private temporary file.

func CanonicalExistingDirectory

func CanonicalExistingDirectory(path string) (string, error)

CanonicalExistingDirectory returns the absolute symlink-resolved identity of an existing directory.

func CanonicalPathWithExistingPrefix

func CanonicalPathWithExistingPrefix(path string) (string, error)

CanonicalPathWithExistingPrefix resolves symlinks in the deepest existing prefix while preserving any missing suffix components.

func CheckPrivateFile

func CheckPrivateFile(file *os.File) error

CheckPrivateFile validates permissions on the same regular-file handle used for I/O.

func OpenRegularFile

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

OpenRegularFile opens a regular file through a non-following directory chain.

func PathWithinRoot

func PathWithinRoot(root string, candidate string) (bool, error)

PathWithinRoot reports whether candidate is lexically contained by root. Callers that need physical identity containment must resolve paths first.

func ReadPrivateFile

func ReadPrivateFile(path string) ([]byte, error)

ReadPrivateFile refuses unsafe paths and permissions before reading bytes.

func ReadRegularFile

func ReadRegularFile(path string) (contents []byte, info os.FileInfo, err error)

ReadRegularFile reads a regular file through a non-following directory chain. It returns the metadata observed through that same file handle.

func ResolveExistingPathWithinRoot

func ResolveExistingPathWithinRoot(root string, candidate string) (
	resolvedRoot string,
	resolvedCandidate string,
	err error,
)

ResolveExistingPathWithinRoot resolves two existing paths and verifies that candidate remains within root after following symlinks.

func ResolvePathWithinRoot

func ResolvePathWithinRoot(root string, target string) (string, error)

ResolvePathWithinRoot resolves a target path and validates it remains under root.

func SyncDir

func SyncDir(path string) (err error)

SyncDir requests a directory metadata flush using a mutation-capable handle.

func ValidatePathComponent

func ValidatePathComponent(component string) error

ValidatePathComponent accepts exactly one portable filename component. It rejects names whose interpretation differs across supported platforms.

Types

type Directory

type Directory struct {
	// contains filtered or unexported fields
}

Directory is a directory acquired without following symlinks or reparse points.

func OpenDirectory

func OpenDirectory(path string) (*Directory, error)

OpenDirectory opens a directory through a non-following directory chain.

func OpenDirectoryForMutation

func OpenDirectoryForMutation(path string) (*Directory, error)

OpenDirectoryForMutation opens a directory with the rights required for child creation and atomic publication.

func OpenOrCreateDirectory

func OpenOrCreateDirectory(path string, perm os.FileMode) (*Directory, error)

OpenOrCreateDirectory opens a non-link directory chain, creating missing directories.

func OpenOrCreateParentDirectory

func OpenOrCreateParentDirectory(path string, perm os.FileMode) (*Directory, string, error)

OpenOrCreateParentDirectory opens or creates the parent directory and returns the target basename.

func OpenParentDirectory

func OpenParentDirectory(path string) (*Directory, string, error)

OpenParentDirectory opens the existing parent directory and returns the target basename.

func (*Directory) AtomicWriteFile

func (d *Directory) AtomicWriteFile(name string, contents []byte, perm os.FileMode, replace bool) (err error)

AtomicWriteFile writes a direct child through a temporary file and publishes it atomically. When replace is false, publication fails if a child with name already exists.

func (*Directory) CheckPrivatePermissions

func (d *Directory) CheckPrivatePermissions() error

CheckPrivatePermissions validates the held directory's Windows owner and ACL.

func (*Directory) Chmod

func (d *Directory) Chmod(mode os.FileMode) error

Chmod changes permissions through the held directory handle.

func (*Directory) Close

func (d *Directory) Close() error

Close releases the directory handle.

func (*Directory) CopyContentsFrom

func (d *Directory) CopyContentsFrom(source *Directory, excludedName string) error

CopyContentsFrom copies every child from source into d, excluding one direct child name.

func (*Directory) CreateDirectory

func (d *Directory) CreateDirectory(name string, perm os.FileMode) (*Directory, error)

CreateDirectory creates and opens one direct child directory without following links.

func (*Directory) CreateRegularFile

func (d *Directory) CreateRegularFile(name string, perm os.FileMode) (*os.File, error)

CreateRegularFile creates one direct regular-file child without following links.

func (*Directory) CreateTemporaryDirectory

func (d *Directory) CreateTemporaryDirectory(prefix string, perm os.FileMode) (string, *Directory, error)

CreateTemporaryDirectory creates and opens a direct child directory with a cryptographically random suffix.

func (*Directory) MoveRegularFileNoReplace

func (d *Directory) MoveRegularFileNoReplace(
	source *os.File,
	sourceName string,
	targetName string,
) (committed bool, err error)

MoveRegularFileNoReplace moves one direct regular-file child while retaining the supplied source handle for platform identity binding. The committed result stays true when only the durability sync fails.

func (*Directory) MoveTo

func (d *Directory) MoveTo(target *Directory, targetName string, replace bool) (DirectoryMoveResult, error)

MoveTo publishes the directory capability opened by OpenDirectoryForMove. A committed result retains any subsequent durability failure in PostCommitErr, so callers can never mistake it for a failed rename.

func (*Directory) OpenDirectory

func (d *Directory) OpenDirectory(name string) (*Directory, error)

OpenDirectory opens a direct child directory from the held directory handle.

func (*Directory) OpenDirectoryForMove

func (d *Directory) OpenDirectoryForMove(name string) (*Directory, error)

OpenDirectoryForMove opens a direct child directory with the rights and identity proof required to publish that exact directory through MoveTo.

func (*Directory) OpenDirectoryForMutation

func (d *Directory) OpenDirectoryForMutation(name string) (*Directory, error)

OpenDirectoryForMutation opens a direct child directory with the rights required for child creation and atomic publication.

func (*Directory) OpenRegularFile

func (d *Directory) OpenRegularFile(name string) (*os.File, error)

OpenRegularFile opens a direct child regular file from the held directory handle.

func (*Directory) ReadDir

func (d *Directory) ReadDir() ([]string, error)

ReadDir returns the names enumerated from the held directory handle.

func (*Directory) ReadPrivateFile

func (d *Directory) ReadPrivateFile(name string) ([]byte, error)

ReadPrivateFile reads a private child from the held directory.

func (*Directory) ReadRegularFile

func (d *Directory) ReadRegularFile(name string) (contents []byte, info os.FileInfo, err error)

ReadRegularFile reads a direct child regular file from the held directory handle.

func (*Directory) RemoveAll

func (d *Directory) RemoveAll(name string) error

RemoveAll removes a direct child tree without traversing links; an absent child counts as removed.

func (*Directory) RemoveBoundRegularFile

func (d *Directory) RemoveBoundRegularFile(source *os.File, sourceName string) error

RemoveBoundRegularFile removes the exact regular file retained by source. A replacement at sourceName is rejected without removing that replacement.

func (*Directory) RemoveBoundTree

func (d *Directory) RemoveBoundTree() error

RemoveBoundTree removes the exact directory held by a move capability. The directory is first moved into a private parent, so a replacement at its public name cannot be traversed or deleted.

func (*Directory) RemoveRegularFile

func (d *Directory) RemoveRegularFile(name string) (err error)

RemoveRegularFile removes a direct regular-file child without following links.

func (*Directory) ReopenForMutation

func (d *Directory) ReopenForMutation(path string) (*Directory, error)

ReopenForMutation acquires write rights only if the path still names this held directory.

func (*Directory) Stat

func (d *Directory) Stat() (os.FileInfo, error)

Stat returns metadata from the held directory handle.

func (*Directory) Sync

func (d *Directory) Sync() error

Sync flushes held directory metadata when the platform supports it. On Windows, the Directory must have been opened for mutation because the OS requires write access for FlushFileBuffers.

type DirectoryMoveResult

type DirectoryMoveResult struct {
	State         DirectoryMoveState
	PostCommitErr error
}

DirectoryMoveResult reports whether the canonical target changed. A PostCommitErr never means a caller may attempt to undo the completed move.

func (DirectoryMoveResult) Collision

func (r DirectoryMoveResult) Collision() bool

Collision reports whether no-replace publication found an existing target.

func (DirectoryMoveResult) Committed

func (r DirectoryMoveResult) Committed() bool

Committed reports whether the destination rename completed.

type DirectoryMoveState

type DirectoryMoveState uint8

DirectoryMoveState separates effects that have not reached the canonical target from an irrevocably committed rename.

const (
	DirectoryMovePreCommit DirectoryMoveState = iota
	DirectoryMoveCollision
	DirectoryMoveCommitted
)

type MoveRecoveryError

type MoveRecoveryError struct {
	TransactionName string
	CandidateName   string
	Cause           error
}

MoveRecoveryError identifies a preserved private transaction and its retained entry.

func (*MoveRecoveryError) Error

func (e *MoveRecoveryError) Error() string

func (*MoveRecoveryError) Unwrap

func (e *MoveRecoveryError) Unwrap() []error

Unwrap preserves both the stable recovery classification and its cause.

type TarGzipLimits

type TarGzipLimits struct {
	MaxCompressedSize   int64
	MaxUncompressedSize int64
	MaxFileCount        int
}

TarGzipLimits bounds the archive while it is produced. Non-positive values disable a limit.

type TarGzipStats

type TarGzipStats struct {
	CompressedSize   int64
	UncompressedSize int64
	FileCount        int
}

TarGzipStats reports bytes and entries accepted before completion or failure.

func WriteTarGzipDirectory

func WriteTarGzipDirectory(
	ctx context.Context,
	destination io.Writer,
	root string,
	excludeTopLevel map[string]struct{},
	limits TarGzipLimits,
) (stats TarGzipStats, err error)

WriteTarGzipDirectory writes a deterministic gzip-compressed tar stream. Names in excludeTopLevel omit matching entries directly below root.

type TarLimits

type TarLimits struct {
	MaxBytes     int64
	MaxFileCount int
}

TarLimits bounds raw TAR bytes and entries; nonpositive values disable each limit.

type TarStats

type TarStats struct {
	Bytes     int64
	FileCount int
}

TarStats reports raw TAR bytes and counted entries, including partial writes.

func WriteTarDirectory

func WriteTarDirectory(
	ctx context.Context,
	destination io.Writer,
	root string,
	excludeTopLevel map[string]struct{},
	limits TarLimits,
) (stats TarStats, err error)

WriteTarDirectory writes canonical raw TAR, excluding named top-level entries and their descendants.

Jump to

Keyboard shortcuts

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