Documentation
¶
Overview ¶
Package fileutil provides shared filesystem helpers for Compozy components.
Index ¶
- Variables
- func AtomicRemoveFile(path string) (err error)
- func AtomicWrite(path string, content []byte) error
- func AtomicWriteFile(path string, content []byte, perm os.FileMode) (err error)
- func CanonicalExistingDirectory(path string) (string, error)
- func CanonicalPathWithExistingPrefix(path string) (string, error)
- func OpenRegularFile(path string) (*os.File, error)
- func PathWithinRoot(root string, candidate string) (bool, error)
- func ReadRegularFile(path string) (contents []byte, info os.FileInfo, err error)
- func ResolveExistingPathWithinRoot(root string, candidate string) (resolvedRoot string, resolvedCandidate string, err error)
- func ResolvePathWithinRoot(root string, target string) (string, error)
- func SyncDir(path string) (err error)
- func ValidatePathComponent(component string) error
- type Directory
- func OpenDirectory(path string) (*Directory, error)
- func OpenDirectoryForMutation(path string) (*Directory, error)
- func OpenOrCreateDirectory(path string, perm os.FileMode) (*Directory, error)
- func OpenOrCreateParentDirectory(path string, perm os.FileMode) (*Directory, string, error)
- func OpenParentDirectory(path string) (*Directory, string, error)
- func (d *Directory) AtomicWriteFile(name string, contents []byte, perm os.FileMode, replace bool) (err error)
- func (d *Directory) Chmod(mode os.FileMode) error
- func (d *Directory) Close() error
- func (d *Directory) CopyContentsFrom(source *Directory, excludedName string) error
- func (d *Directory) CreateDirectory(name string, perm os.FileMode) (*Directory, error)
- func (d *Directory) CreateRegularFile(name string, perm os.FileMode) (*os.File, error)
- func (d *Directory) CreateTemporaryDirectory(prefix string, perm os.FileMode) (string, *Directory, error)
- func (d *Directory) MoveRegularFileNoReplace(source *os.File, sourceName string, targetName string) (committed bool, err error)
- func (d *Directory) MoveTo(target *Directory, targetName string, replace bool) (DirectoryMoveResult, error)
- func (d *Directory) OpenDirectory(name string) (*Directory, error)
- func (d *Directory) OpenDirectoryForMove(name string) (*Directory, error)
- func (d *Directory) OpenDirectoryForMutation(name string) (*Directory, error)
- func (d *Directory) OpenRegularFile(name string) (*os.File, error)
- func (d *Directory) ReadDir() ([]string, error)
- func (d *Directory) ReadRegularFile(name string) (contents []byte, info os.FileInfo, err error)
- func (d *Directory) RemoveAll(name string) error
- func (d *Directory) RemoveBoundRegularFile(source *os.File, sourceName string) error
- func (d *Directory) RemoveBoundTree() error
- func (d *Directory) RemoveRegularFile(name string) (err error)
- func (d *Directory) ReopenForMutation(path string) (*Directory, error)
- func (d *Directory) Stat() (os.FileInfo, error)
- func (d *Directory) Sync() error
- type DirectoryMoveResult
- type DirectoryMoveState
- type MoveRecoveryError
- type TarGzipLimits
- type TarGzipStats
- type TarLimits
- type TarStats
Constants ¶
This section is empty.
Variables ¶
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") )
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") )
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") )
var ErrInvalidPath = errors.New("fileutil: invalid path")
ErrInvalidPath reports a path that cannot be represented safely by the filesystem boundary.
var ErrPathOutsideRoot = errors.New("fileutil: resolved path is outside root")
ErrPathOutsideRoot identifies a path whose resolved target escapes the resolved root.
var ErrPathRootRequired = errors.New("fileutil: root path is required")
ErrPathRootRequired reports a blank root in a containment request.
Functions ¶
func AtomicRemoveFile ¶
AtomicRemoveFile removes a file and syncs its parent directory.
func AtomicWrite ¶
AtomicWrite writes content with the default Compozy file permissions via temp-file-and-rename.
func AtomicWriteFile ¶
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 CanonicalExistingDirectory ¶
CanonicalExistingDirectory returns the absolute symlink-resolved identity of an existing directory.
func CanonicalPathWithExistingPrefix ¶
CanonicalPathWithExistingPrefix resolves symlinks in the deepest existing prefix while preserving any missing suffix components.
func OpenRegularFile ¶
OpenRegularFile opens a regular file through a non-following directory chain.
func PathWithinRoot ¶
PathWithinRoot reports whether candidate is lexically contained by root. Callers that need physical identity containment must resolve paths first.
func ReadRegularFile ¶
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 ¶
ResolvePathWithinRoot resolves a target path and validates it remains under root.
func ValidatePathComponent ¶
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 ¶
OpenDirectory opens a directory through a non-following directory chain.
func OpenDirectoryForMutation ¶
OpenDirectoryForMutation opens a directory with the rights required for child creation and atomic publication.
func OpenOrCreateDirectory ¶
OpenOrCreateDirectory opens a non-link directory chain, creating missing directories.
func OpenOrCreateParentDirectory ¶
OpenOrCreateParentDirectory opens or creates the parent directory and returns the target basename.
func OpenParentDirectory ¶
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) CopyContentsFrom ¶
CopyContentsFrom copies every child from source into d, excluding one direct child name.
func (*Directory) CreateDirectory ¶
CreateDirectory creates and opens one direct child directory without following links.
func (*Directory) CreateRegularFile ¶
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 ¶
OpenDirectory opens a direct child directory from the held directory handle.
func (*Directory) OpenDirectoryForMove ¶
OpenDirectoryForMove opens a direct child directory with the rights and identity proof required to publish that exact directory through MoveTo.
func (*Directory) OpenDirectoryForMutation ¶
OpenDirectoryForMutation opens a direct child directory with the rights required for child creation and atomic publication.
func (*Directory) OpenRegularFile ¶
OpenRegularFile opens a direct child regular file from the held directory handle.
func (*Directory) ReadRegularFile ¶
ReadRegularFile reads a direct child regular file from the held directory handle.
func (*Directory) RemoveAll ¶
RemoveAll removes a direct child tree without traversing links; an absent child counts as removed.
func (*Directory) RemoveBoundRegularFile ¶
RemoveBoundRegularFile removes the exact regular file retained by source. A replacement at sourceName is rejected without removing that replacement.
func (*Directory) RemoveBoundTree ¶
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 ¶
RemoveRegularFile removes a direct regular-file child without following links.
func (*Directory) ReopenForMutation ¶
ReopenForMutation acquires write rights only if the path still names this held directory.
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 ¶
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 ¶
TarGzipLimits bounds the archive while it is produced. Non-positive values disable a limit.
type TarGzipStats ¶
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.
Source Files
¶
- atomic.go
- close_owner.go
- directory_move.go
- directory_move_identity_unix.go
- directory_move_linux.go
- directory_move_unix.go
- directory_remove_bound.go
- directory_remove_bound_unix.go
- move_recovery_unix.go
- nofollow.go
- nofollow_unix.go
- path_component.go
- path_containment.go
- regular_file_move.go
- regular_file_move_unix.go
- rooted_write.go
- rooted_write_unix.go
- system_root_alias_unix.go
- targzip.go